starlight-cli 1.1.4 → 1.1.6

package/README.md

@@ -1,65 +1,53 @@
-# Starlight Language
+
+# Starlight Programming Language 
 
 Starlight is a lightweight, developer-oriented programming language designed for **server-side scripting, automation, and general-purpose programming**. It combines a clean, readable syntax inspired by JavaScript and Python with powerful runtime features such as async/await, modules, and interactive I/O.
 
-**Official Reference:** [
+ **Official Reference:**  
+https://starlight-learn-lang.pages.dev/
 
 ---
 
 ## Key Features
 
-
-  - **Modern, Simple Syntax** – Familiar to JavaScript and Python developers
-  - **Async / Await** – Native support for asynchronous operations
-  - **Modules & Imports** – Import JavaScript packages or other `.sl` files
-  - **Server-side Ready** – Built on Node.js, ideal for backend logic
-  - **Interactive I/O** – Built-in `ask` and `sldeploy`
-  - **Built-in Utilities** – `sleep`, `len`, `keys`, `values`, `fetch`, `get`, `post`
-
+- **Modern, Simple Syntax** – Familiar to JavaScript and Python developers
+- **Async / Await** – Native support for asynchronous operations
+- **Modules & Imports** – Import JavaScript packages or other `.sl` files
+- **Server-side Ready** – Built on Node.js, ideal for backend logic
+- **Interactive I/O** – Built-in `ask` and `sldeploy`
+- **Built-in Utilities** – `sleep`, `len`, `keys`, `values`, `fetch`, `get`, `post`
 
 ---
 
 ## Installation
 
+1. Install **Node.js** (v18+ recommended)
+2. Install the Starlight CLI:
 
-  Install **Node.js** (v18+ recommended)1. $1
-  Install Starlight CLI:1. $1
-
-
-```
-
+```bash
 npm install -g starlight-cli
-
-```
+````
 
 ---
 
 ## Your First Program (`hello.sl`)
 
-```
-
+```sl
 let name = ask("What is your name?")
 sldeploy "Hello, " + name + "!"
-
 ```
 
 Run:
 
-```
-
+```bash
 starlight hello.sl
-
 ```
 
----
-
-## Output
-
-```
+### Output
 
+```
 What is your name? Alice
 Hello, Alice!
-
 ```
 
 ---
@@ -68,68 +56,59 @@ Hello, Alice!
 
 ### Variables
 
-```
-
+```sl
 let x = 10
 let text = "hello"
-
 ```
 
 ---
 
 ### Functions
 
-```
-
+```sl
 func add(a, b) {
   return a + b
 }
 
 sldeploy add(2, 3)
-
 ```
 
-### Async Functions
+---
 
-```
+### Async Functions
 
+```sl
 async func load() {
   let data = await get("https://example.com/api")
   sldeploy data
 }
 
 load()
-
 ```
 
 ---
 
 ## Arrow Functions
 
-Arrow functions provide a **concise and expressive** way to define functions. They support expressions, block bodies, conditionals, loops, and `return` statements.
+Arrow functions provide a **concise and expressive** way to define functions.
 
 ### Basic Arrow Function
 
-```
-
+```sl
 let square = x => x * x
 sldeploy square(5)
-
 ```
 
 ### Multiple Parameters
 
-```
-
+```sl
 let add = (a, b) => a + b
 sldeploy add(10, 20)
-
 ```
 
 ### Block Body with if / else
 
-```
-
+```sl
 let label = p => {
   if (p.price > 1000) {
     return "Premium"
@@ -137,20 +116,17 @@ let label = p => {
     return "Standard"
   }
 }
-
 ```
 
 ### Arrow Functions with Objects
 
-```
-
+```sl
 let summarize = p => {
   return {
     "name": p.name,
     "value": p.price * p.stock
   }
 }
-
 ```
 
 Arrow functions capture their surrounding scope and behave like standard functions while remaining lightweight and readable.
@@ -159,14 +135,12 @@ Arrow functions capture their surrounding scope and behave like standard functio
 
 ## Conditionals
 
-```
-
+```sl
 if (x > 5) {
   sldeploy "Greater than 5"
 } else {
   sldeploy "5 or less"
 }
-
 ```
 
 ---
@@ -175,16 +149,12 @@ if (x > 5) {
 
 ### While Loop
 
-```
-
+```sl
 let i = 0
-while (i  {
-  let response = await get("https://jsonplaceholder.typicode.com/todos/1")
-  sldeploy response
+while (i < 3) {
+  sldeploy i
+  i = i + 1
 }
-
-server()
-
 ```
 
 ---
@@ -195,8 +165,7 @@ Starlight includes a **start / race** control structure similar to a switch stat
 
 ### Syntax
 
-```
-
+```sl
 start (value) {
   race (1) {
     # body
@@ -206,49 +175,210 @@ start (value) {
     # body
   }
 }
-
 ```
 
 ### Example
 
-```
-
-define x = 2;
+```sl
+define x = 2
 
 start (x) {
-  race (1) { sldeploy("Race 1 executed"); }
-  race (2) { sldeploy("Race 2 executed"); }
-  race (3) { sldeploy("Race 3 executed"); }
+  race (1) { sldeploy("Race 1 executed") }
+  race (2) { sldeploy("Race 2 executed") }
+  race (3) { sldeploy("Race 3 executed") }
 }
 
-sldeploy("Done with start statement");
-
+sldeploy("Done with start statement")
 ```
 
 ### Expected Output
 
-```
-
+```
 Race 2 executed
 Race 3 executed
 Done with start statement
-
 ```
 
 ---
 
-## Why Starlight?
+## Markdown Preview (`starlight filename.md`)
+
+Starlight can also be used to **preview Markdown files** directly from the CLI.
+
+### Usage
+
+```bash
+starlight README.md
+```
+
+### How It Works (Execution Flow)
+
+1. The CLI detects the `.md` file extension
+2. The Markdown file is read from disk
+3. Markdown is converted to HTML using a full-featured Markdown renderer
+4. A **temporary HTML file** is created in the system temp directory
+5. The file is opened in your default browser using `file://`
+6. After the browser loads, the temporary file is **automatically deleted**
+
+This makes Starlight useful not only as a programming language, but also as a **developer productivity tool**.
+
+---
+
+## 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:**
+```
 
-  - A **simple but powerful** scripting language
-  - **Fast server-side automation**
-  - Familiar syntax with **less boilerplate**
-  - Full access to the **Node.js ecosystem**
+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
+* **Fast server-side automation**
+* Familiar syntax with **less boilerplate**
+* Full access to the **Node.js ecosystem**
 
 ---
 
-📘 Full documentation and tutorials:
-https://starlight-learn-lang.pages.dev/](https://starlight-learn-lang.pages.dev/>https://starlight-learn-lang.pages.dev/</link)
+## License
+
+MIT License
+
+---
 
-**License:** MIT
+## Author and Developer
+Dominex Macedon