@forthix/forthic 0.10.0 → 0.12.0

package/dist/esm/forthic/modules/standard/array_module.js

@@ -5,20 +5,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { dup_interpreter } from "../../interpreter.js";
-import { DecoratedModule, ForthicWord, ForthicDirectWord, registerModuleDoc } from "../../decorators/word.js";
+import { DecoratedModule, ForthicWord, registerModuleDoc } from "../../decorators/word.js";
 export class ArrayModule extends DecoratedModule {
     static {
         registerModuleDoc(ArrayModule, `
 Array and collection operations for manipulating arrays and records.
 
 ## Categories
-- Access: NTH, LAST, SLICE, TAKE, DROP, LENGTH, INDEX, KEY-OF
-- Transform: MAP, REVERSE
-- Combine: APPEND, ZIP, ZIP_WITH, CONCAT
-- Filter: SELECT, UNIQUE, DIFFERENCE, INTERSECTION, UNION
-- Sort: SORT, SHUFFLE, ROTATE
-- Group: BY_FIELD, GROUP-BY-FIELD, GROUP_BY, GROUPS_OF
-- Utility: <REPEAT, FOREACH, REDUCE, UNPACK, FLATTEN
+- Access: NTH, FIRST, LAST, SLICE, TAKE, TAKE-LAST, SKIP, LENGTH, INDEX, KEY-OF
+- Transform: MAP, MAP-AT, REVERSE
+- Combine: APPEND, ZIP, ZIP-WITH
+- Filter: FILTER, UNIQUE, UNIQUE-BY, DIFFERENCE, INTERSECTION, UNION
+- Sort: SORT, SORT-BY, SORT-U
+- Search: FIND, COUNT
+- Extrema: MIN-BY, MAX-BY
+- Indexing: NUMBERED
+- Group: BY-FIELD, GROUP-BY, GROUP-BY-FIELD, GROUPS-OF
+- Iteration: FOREACH, REDUCE, UNPACK, FLATTEN, TIMES-RUN
 
 ## Options
 Several words support options via the ~> operator using syntax: [.option_name value ...] ~> WORD
@@ -39,17 +42,14 @@ Several words support options via the ~> operator using syntax: [.option_name va
     constructor() {
         super("array");
     }
-    async APPEND(container, item) {
-        let result = container;
-        if (!result)
+    async APPEND(array, item) {
+        let result = array;
+        if (result === null || result === undefined)
             result = [];
-        if (result instanceof Array) {
-            result.push(item);
-        }
-        else {
-            // If not a list, treat as record - item should be [key, value]
-            result[item[0]] = item[1];
+        if (!(result instanceof Array)) {
+            throw new Error("APPEND requires an array. For records, use JQ! to set a key.");
         }
+        result.push(item);
         return result;
     }
     async REVERSE(container) {
@@ -71,14 +71,16 @@ Several words support options via the ~> operator using syntax: [.option_name va
         return result;
     }
     async LENGTH(container) {
-        if (!container)
+        if (container === null || container === undefined)
             return 0;
-        if (container instanceof Array) {
+        if (container instanceof Array)
             return container.length;
+        if (typeof container === "string") {
+            throw new Error("LENGTH operates on arrays and records. For strings, use STR-LENGTH.");
         }
-        else {
+        if (typeof container === "object")
             return Object.keys(container).length;
-        }
+        throw new Error("LENGTH operates on arrays and records.");
     }
     async NTH(container, n) {
         if (n === null || !container)
@@ -96,6 +98,21 @@ Several words support options via the ~> operator using syntax: [.option_name va
             return container[key];
         }
     }
+    async FIRST(container) {
+        if (!container)
+            return null;
+        if (container instanceof Array) {
+            if (container.length === 0)
+                return null;
+            return container[0];
+        }
+        else {
+            const keys = Object.keys(container).sort();
+            if (keys.length === 0)
+                return null;
+            return container[keys[0]];
+        }
+    }
     async LAST(container) {
         if (!container)
             return null;
@@ -194,7 +211,7 @@ Several words support options via the ~> operator using syntax: [.option_name va
         }
         return taken;
     }
-    async DROP(container, n) {
+    async SKIP(container, n) {
         if (!container)
             return [];
         if (n <= 0)
@@ -208,6 +225,23 @@ Several words support options via the ~> operator using syntax: [.option_name va
             return rest_keys.map((k) => container[k]);
         }
     }
+    async TAKE_LAST(container, n) {
+        if (!container)
+            return [];
+        if (n <= 0)
+            return container instanceof Array ? [] : {};
+        if (container instanceof Array) {
+            return container.slice(Math.max(0, container.length - n));
+        }
+        else {
+            const keys = Object.keys(container).sort();
+            const tail = keys.slice(Math.max(0, keys.length - n));
+            const result = {};
+            for (const k of tail)
+                result[k] = container[k];
+            return result;
+        }
+    }
     async DIFFERENCE(lcontainer, rcontainer) {
         let _lcontainer = lcontainer || [];
         let _rcontainer = rcontainer || [];
@@ -364,29 +398,6 @@ Several words support options via the ~> operator using syntax: [.option_name va
         }
         return result;
     }
-    async SHUFFLE(array) {
-        if (!array)
-            return array;
-        const result = [...array];
-        for (let i = result.length - 1; i > 0; i--) {
-            const j = Math.floor(Math.random() * (i + 1));
-            [result[i], result[j]] = [result[j], result[i]];
-        }
-        return result;
-    }
-    async ROTATE(container) {
-        if (!container)
-            return container;
-        let result = container;
-        if (container instanceof Array) {
-            if (container.length > 0) {
-                result = [...container];
-                const val = result.pop();
-                result.unshift(val);
-            }
-        }
-        return result;
-    }
     async UNPACK(container) {
         let _container = container;
         if (!_container)
@@ -599,7 +610,7 @@ Several words support options via the ~> operator using syntax: [.option_name va
             return null;
         }
     }
-    async SELECT(container, forthic, options) {
+    async FILTER(container, forthic, options) {
         const interp = this.interp;
         const string_location = interp.get_string_location();
         const flags = {
@@ -814,24 +825,207 @@ Several words support options via the ~> operator using syntax: [.option_name va
         await map_word.execute(this.interp);
         return undefined; // MapWord pushes result directly
     }
-    async l_REPEAT(interp) {
-        const num_times = interp.stack_pop();
-        const forthic = interp.stack_pop();
-        const string_location = interp.get_string_location();
+    async MAP_AT(container, key, forthic) {
+        if (container === null || container === undefined)
+            return container;
+        const string_location = this.interp.get_string_location();
+        // Path-array form: walk the path, transforming the value at the leaf
+        if (Array.isArray(key)) {
+            if (key.length === 0) {
+                // Apply forthic to the entire container
+                this.interp.stack_push(container);
+                await this.interp.run(forthic, string_location);
+                return this.interp.stack_pop();
+            }
+            const [head, ...rest] = key;
+            return this._mapAtRecursive(container, head, rest, forthic, string_location);
+        }
+        // Single-key form
+        return this._mapAtSingle(container, key, forthic, string_location);
+    }
+    async _mapAtRecursive(container, head, rest, forthic, string_location) {
+        if (rest.length === 0) {
+            return this._mapAtSingle(container, head, forthic, string_location);
+        }
+        if (container instanceof Array) {
+            const idx = typeof head === "number" ? head : Number(head);
+            if (!Number.isInteger(idx) || idx < 0 || idx >= container.length)
+                return container;
+            const result = [...container];
+            result[idx] = await this._mapAtRecursive(result[idx], rest[0], rest.slice(1), forthic, string_location);
+            return result;
+        }
+        if (typeof container === "object" && container !== null) {
+            if (!Object.prototype.hasOwnProperty.call(container, head))
+                return container;
+            const result = { ...container };
+            result[head] = await this._mapAtRecursive(result[head], rest[0], rest.slice(1), forthic, string_location);
+            return result;
+        }
+        return container;
+    }
+    async _mapAtSingle(container, key, forthic, string_location) {
+        if (container instanceof Array) {
+            const idx = typeof key === "number" ? key : Number(key);
+            if (!Number.isInteger(idx) || idx < 0 || idx >= container.length)
+                return container;
+            const result = [...container];
+            this.interp.stack_push(result[idx]);
+            await this.interp.run(forthic, string_location);
+            result[idx] = this.interp.stack_pop();
+            return result;
+        }
+        if (typeof container === "object" && container !== null) {
+            if (!Object.prototype.hasOwnProperty.call(container, key))
+                return container;
+            const result = { ...container };
+            this.interp.stack_push(result[key]);
+            await this.interp.run(forthic, string_location);
+            result[key] = this.interp.stack_pop();
+            return result;
+        }
+        return container;
+    }
+    async TIMES_RUN(num_times, forthic) {
+        if (num_times === null || num_times === undefined || !forthic)
+            return;
+        const string_location = this.interp.get_string_location();
         for (let i = 0; i < num_times; i++) {
-            // Store item so we can push it back later
-            const item = interp.stack_pop();
-            interp.stack_push(item);
-            await interp.run(forthic, string_location);
-            const res = interp.stack_pop();
-            // Push original item and result
-            interp.stack_push(item);
-            interp.stack_push(res);
+            await this.interp.run(forthic, string_location);
+        }
+    }
+    // ========================================
+    // Functional / jq-style additions
+    // ========================================
+    async FIND(items, forthic) {
+        if (!items)
+            return null;
+        const string_location = this.interp.get_string_location();
+        const seq = items instanceof Array ? items : Object.keys(items).map((k) => items[k]);
+        for (const item of seq) {
+            this.interp.stack_push(item);
+            await this.interp.run(forthic, string_location);
+            const matched = this.interp.stack_pop();
+            if (matched)
+                return item;
+        }
+        return null;
+    }
+    async COUNT(items, forthic) {
+        if (!items)
+            return 0;
+        const string_location = this.interp.get_string_location();
+        const seq = items instanceof Array ? items : Object.keys(items).map((k) => items[k]);
+        let n = 0;
+        for (const item of seq) {
+            this.interp.stack_push(item);
+            await this.interp.run(forthic, string_location);
+            if (this.interp.stack_pop())
+                n++;
+        }
+        return n;
+    }
+    async SORT_BY(items, forthic) {
+        if (!Array.isArray(items))
+            return items;
+        const string_location = this.interp.get_string_location();
+        const decorated = [];
+        for (const item of items) {
+            this.interp.stack_push(item);
+            await this.interp.run(forthic, string_location);
+            decorated.push({ item, key: this.interp.stack_pop() });
+        }
+        decorated.sort((a, b) => {
+            if (a.key < b.key)
+                return -1;
+            if (a.key > b.key)
+                return 1;
+            return 0;
+        });
+        return decorated.map((d) => d.item);
+    }
+    async MIN_BY(items, forthic) {
+        if (!Array.isArray(items) || items.length === 0)
+            return null;
+        const string_location = this.interp.get_string_location();
+        let best_item = null;
+        let best_key = null;
+        let first = true;
+        for (const item of items) {
+            this.interp.stack_push(item);
+            await this.interp.run(forthic, string_location);
+            const key = this.interp.stack_pop();
+            if (first || key < best_key) {
+                best_item = item;
+                best_key = key;
+                first = false;
+            }
         }
+        return best_item;
+    }
+    async MAX_BY(items, forthic) {
+        if (!Array.isArray(items) || items.length === 0)
+            return null;
+        const string_location = this.interp.get_string_location();
+        let best_item = null;
+        let best_key = null;
+        let first = true;
+        for (const item of items) {
+            this.interp.stack_push(item);
+            await this.interp.run(forthic, string_location);
+            const key = this.interp.stack_pop();
+            if (first || key > best_key) {
+                best_item = item;
+                best_key = key;
+                first = false;
+            }
+        }
+        return best_item;
+    }
+    async UNIQUE_BY(items, forthic) {
+        if (!Array.isArray(items))
+            return items;
+        const string_location = this.interp.get_string_location();
+        const seen = new Set();
+        const result = [];
+        for (const item of items) {
+            this.interp.stack_push(item);
+            await this.interp.run(forthic, string_location);
+            const key = this.interp.stack_pop();
+            const skey = JSON.stringify(key);
+            if (!seen.has(skey)) {
+                seen.add(skey);
+                result.push(item);
+            }
+        }
+        return result;
+    }
+    async NUMBERED(items) {
+        if (!Array.isArray(items))
+            return [];
+        return items.map((item, i) => [i, item]);
+    }
+    // ========================================
+    // Bash/shell-flavored array additions (PR 7)
+    // ========================================
+    async SORT_U(strings) {
+        if (!Array.isArray(strings))
+            return strings;
+        const sorted = [...strings].sort();
+        const seen = new Set();
+        const result = [];
+        for (const s of sorted) {
+            const key = JSON.stringify(s);
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.push(s);
+            }
+        }
+        return result;
     }
 }
 __decorate([
-    ForthicWord("( container:any item:any -- container:any )", "Append item to array or add key-value to record")
+    ForthicWord("( array:any[] item:any -- array:any[] )", "Append item to array. For records, use JQ! to set a key.", "APPEND")
 ], ArrayModule.prototype, "APPEND", null);
 __decorate([
     ForthicWord("( container:any -- container:any )", "Reverse array")
@@ -840,11 +1034,14 @@ __decorate([
     ForthicWord("( array:any[] -- array:any[] )", "Remove duplicates from array")
 ], ArrayModule.prototype, "UNIQUE", null);
 __decorate([
-    ForthicWord("( container:any -- length:number )", "Get length of array or record")
+    ForthicWord("( container:any -- length:number )", "Length of an array or record. For strings, use STR-LENGTH.")
 ], ArrayModule.prototype, "LENGTH", null);
 __decorate([
     ForthicWord("( container:any n:number -- item:any )", "Get nth element from array or record")
 ], ArrayModule.prototype, "NTH", null);
+__decorate([
+    ForthicWord("( container:any -- item:any )", "Get first element from array or record (sorted-key order for records)")
+], ArrayModule.prototype, "FIRST", null);
 __decorate([
     ForthicWord("( container:any -- item:any )", "Get last element from array or record")
 ], ArrayModule.prototype, "LAST", null);
@@ -855,8 +1052,11 @@ __decorate([
     ForthicWord("( container:any[] n:number [options:WordOptions] -- result:any[] )", "Take first n elements")
 ], ArrayModule.prototype, "TAKE", null);
 __decorate([
-    ForthicWord("( container:any n:number -- result:any )", "Drop first n elements from array or record")
-], ArrayModule.prototype, "DROP", null);
+    ForthicWord("( container:any n:number -- result:any )", "Skip first n elements from array or record")
+], ArrayModule.prototype, "SKIP", null);
+__decorate([
+    ForthicWord("( container:any n:number -- result:any )", "Take last n elements from array or record (sorted-key order for records).", "TAKE-LAST")
+], ArrayModule.prototype, "TAKE_LAST", null);
 __decorate([
     ForthicWord("( lcontainer:any rcontainer:any -- result:any )", "Set difference between two containers")
 ], ArrayModule.prototype, "DIFFERENCE", null);
@@ -869,12 +1069,6 @@ __decorate([
 __decorate([
     ForthicWord("( container:any[] [options:WordOptions] -- array:any[] )", "Sort container. Options: comparator (string or function). Example: [3 1 4] [.comparator \"-1 *\"] ~> SORT")
 ], ArrayModule.prototype, "SORT", null);
-__decorate([
-    ForthicWord("( array:any[] -- array:any[] )", "Shuffle array randomly")
-], ArrayModule.prototype, "SHUFFLE", null);
-__decorate([
-    ForthicWord("( container:any -- container:any )", "Rotate container by moving last element to front")
-], ArrayModule.prototype, "ROTATE", null);
 __decorate([
     ForthicWord("( container:any -- elements:any )", "Unpack array or record elements onto stack")
 ], ArrayModule.prototype, "UNPACK", null);
@@ -897,8 +1091,8 @@ __decorate([
     ForthicWord("( container:any value:any -- key:any )", "Find key of value in container", "KEY-OF")
 ], ArrayModule.prototype, "KEY_OF", null);
 __decorate([
-    ForthicWord("( container:any forthic:string [options:WordOptions] -- filtered:any )", "Filter items with predicate. Options: with_key (bool)")
-], ArrayModule.prototype, "SELECT", null);
+    ForthicWord("( container:any forthic:string [options:WordOptions] -- filtered:any )", "Filter items with predicate. Options: with_key (bool)", "FILTER")
+], ArrayModule.prototype, "FILTER", null);
 __decorate([
     ForthicWord("( container:any[] field:string -- indexed:any )", "Index records by field value", "BY-FIELD")
 ], ArrayModule.prototype, "BY_FIELD", null);
@@ -918,8 +1112,35 @@ __decorate([
     ForthicWord("( items:any forthic:string [options:WordOptions] -- mapped:any )", "Map function over items. Options: with_key (bool), push_error (bool), depth (num), push_rest (bool). Example: [1 2 3] '2 *' [.with_key TRUE] ~> MAP")
 ], ArrayModule.prototype, "MAP", null);
 __decorate([
-    ForthicDirectWord("( item:any forthic:string num_times:number -- )", "Repeat execution of forthic num_times", "<REPEAT")
-], ArrayModule.prototype, "l_REPEAT", null);
+    ForthicWord("( container:any key:any|any[] forthic:string -- container:any )", "Apply forthic to the value at key/index, returning a new container with that slot transformed. The key arg may be a single key (one-level update) or a path-array for deep updates. Polymorphic over arrays and records. Equivalent of jq's |= operator.", "MAP-AT")
+], ArrayModule.prototype, "MAP_AT", null);
+__decorate([
+    ForthicWord("( num_times:number forthic:string -- )", "Run forthic num_times. Each invocation runs in the current stack — no automatic per-iteration value passing.", "TIMES-RUN")
+], ArrayModule.prototype, "TIMES_RUN", null);
+__decorate([
+    ForthicWord("( items:any forthic:string -- item:any )", "Return the first item where forthic returns truthy, or null if none.", "FIND")
+], ArrayModule.prototype, "FIND", null);
+__decorate([
+    ForthicWord("( items:any forthic:string -- n:number )", "Count items where forthic returns truthy.", "COUNT")
+], ArrayModule.prototype, "COUNT", null);
+__decorate([
+    ForthicWord("( items:any[] forthic:string -- sorted:any[] )", "Sort items by the value forthic produces (ascending).", "SORT-BY")
+], ArrayModule.prototype, "SORT_BY", null);
+__decorate([
+    ForthicWord("( items:any[] forthic:string -- item:any )", "Return the item with the smallest value produced by forthic. Null on empty input.", "MIN-BY")
+], ArrayModule.prototype, "MIN_BY", null);
+__decorate([
+    ForthicWord("( items:any[] forthic:string -- item:any )", "Return the item with the largest value produced by forthic. Null on empty input.", "MAX-BY")
+], ArrayModule.prototype, "MAX_BY", null);
+__decorate([
+    ForthicWord("( items:any[] forthic:string -- items:any[] )", "Dedupe items by the key forthic produces (keeps first occurrence).", "UNIQUE-BY")
+], ArrayModule.prototype, "UNIQUE_BY", null);
+__decorate([
+    ForthicWord("( items:any[] -- pairs:any[] )", "Pair each item with its index: [v0 v1 v2] -> [[0 v0] [1 v1] [2 v2]]. (Python's enumerate.)", "NUMBERED")
+], ArrayModule.prototype, "NUMBERED", null);
+__decorate([
+    ForthicWord("( strings:any[] -- strings:any[] )", "Sort an array and remove duplicates (bash sort -u).", "SORT-U")
+], ArrayModule.prototype, "SORT_U", null);
 // ( items forthic -- [ ? ] )
 class MapWord {
     forthic;