kopscript 0.15.0 → 0.16.0

package/LLM.md

@@ -238,12 +238,27 @@ limitation, not a semantic one).
 ```ks
 number[] xs = [1, 2, 3];
 xs.Length
-xs.Push(4)                    // NON-mutating — returns a new array, doesn't modify xs
-xs.Map((number x) => x * 2)   // -> array of whatever the callback returns
+xs.Push(4)                            // NON-mutating — returns a new array, doesn't modify xs
+xs.Map((number x) => x * 2)           // -> array of whatever the callback returns
 xs.Filter((number x) => x > 1)
 xs.ForEach((number x) => { print(x); })
+xs.Find((number x) => x > 1)          // -> T?, null if nothing matches
+xs.FindIndex((number x) => x > 1)     // -> number, -1 if nothing matches
+xs.Includes(2)                        // -> bool
+xs.IndexOf(2)                         // -> number, -1 if not present
+xs.Sort((number a, number b) => a - b)  // NON-mutating, comparator always required
+xs.Reverse()                            // NON-mutating
+xs.Slice(1, 2)                        // both bounds always required, no optional params
+xs.Concat(ys)                         // ys: same element type
+xs.Join(", ")                         // -> string; number[]/string[]/bool[] element types only
+xs.Reduce((number acc, number x) => acc + x, 0)  // (acc, initial) — accumulator type = initial's type
 ```
 
+`Push`/`Sort`/`Reverse` are non-mutating (return a new array) — the one deliberate
+departure from real JS, where all three mutate in place; everything else here compiles
+straight to its real `Array.prototype` equivalent. `Reduce`'s argument order matches real
+JS (`reducer, initial`, not the other way around).
+
 ### Strings
 
 ```ks

package/README.md

@@ -676,8 +676,9 @@ KopScript's `string` type exposes PascalCase members that map directly onto
 
 ### Array stdlib
 
-Arrays expose `.Length`, plus `Map`/`Filter`/`ForEach`/`Push`, using lambdas or any other
-function-valued expression (a named function, a variable holding one, ...):
+Arrays expose `.Length`, plus `Map`/`Filter`/`ForEach`/`Push`/`Find`/`FindIndex`/
+`Includes`/`IndexOf`/`Sort`/`Reverse`/`Slice`/`Concat`/`Join`/`Reduce`, using lambdas or
+any other function-valued expression (a named function, a variable holding one, ...):
 
 ```ks
 number[] xs = [1, 2, 3, 4];
@@ -685,21 +686,44 @@ string[] labels = xs.Map((number x) => "n" + x);      // ["n1", "n2", "n3", "n4"
 number[] evens = xs.Filter((number x) => x % 2 == 0);  // [2, 4]
 xs.ForEach((number x) => print(x));
 number[] grown = xs.Push(5);                           // [1, 2, 3, 4, 5]; xs itself is untouched
-```
 
-`Map`/`Filter`/`ForEach` compile straight to their real `Array.prototype` equivalents.
-`Push` is the one departure from JS: it's **non-mutating** (returns a new array; `xs`
-itself is unchanged), unlike JS's own `Array.prototype.push` — chosen for consistency with
-`Map`/`Filter` (already non-mutating) and because nothing else in KopScript's type system models
-aliasing/mutable-reference semantics, so a silently-mutating `Push` would be a surprising
-outlier. It compiles to a plain spread (`[...xs, 5]`), not a `.push()` call.
+number? found = xs.Find((number x) => x > 2);          // 3, or null if nothing matches
+number idx = xs.FindIndex((number x) => x > 2);        // 2, or -1 if nothing matches
+bool has = xs.Includes(3);                              // true
+number at = xs.IndexOf(3);                              // 2, or -1 if not present
+
+number[] sorted = xs.Sort((number a, number b) => a - b);  // new array; xs untouched
+number[] rev = xs.Reverse();                                // new array; xs untouched
+number[] mid = xs.Slice(1, 3);                              // [2, 3]
+number[] joined = xs.Concat([5, 6]);                         // [1, 2, 3, 4, 5, 6]
+string csv = xs.Join(", ");                                 // "1, 2, 3, 4"
+
+number sum = xs.Reduce((number acc, number x) => acc + x, 0);  // 10
+```
+
+`Map`/`Filter`/`ForEach`/`Find`/`FindIndex`/`Includes`/`IndexOf`/`Slice`/`Concat`/`Join`/
+`Reduce` compile straight to their real `Array.prototype` equivalents. `Push`/`Sort`/
+`Reverse` are the departures from JS: all three are **non-mutating** (return a new array;
+the original is unchanged) — unlike JS's own `push`/`sort`/`reverse`, which all mutate in
+place — chosen for consistency and because nothing else in KopScript's type system models
+aliasing/mutable-reference semantics, so a silently-mutating method would be a surprising
+outlier. `Sort`/`Reverse` compile to a spread-copy first (`[...xs].sort(...)`), not a
+direct `.sort()`/`.reverse()` call. `Sort`'s comparator is always required (no
+optional-parameter support in KopScript to fall back on, and it sidesteps real JS
+`Array.sort`'s own well-known footgun — lexicographic-by-default on non-strings). `Slice`'s
+both bounds are likewise always required. `Join` is scoped to primitive element types
+(`number[]`/`string[]`/`bool[]`) only — a class/interface element has no way to customize
+`toString()` in KopScript, so allowing it there would just produce `"[object Object]"`.
 
 `Map`'s result type is the one genuinely polymorphic piece of the whole language — the
 result element type is whatever the callback actually returns, not a fixed signature.
 A plain function reference (`xs.Map(SomeFunction)`) already carries a fully-known type, so
 that case is exact; an inline expression-bodied lambda (`xs.Map((number x) => ...)`) has
 its return type inferred from the body. A block-bodied lambda passed to `Map` is a known
-v1 gap — its result type can't be inferred that way yet.
+v1 gap — its result type can't be inferred that way yet. `Reduce` is similarly
+polymorphic, but simpler to infer: its accumulator type comes directly from the `initial`
+argument (`xs.Reduce(reducer, initial)`, matching real JS's own argument order), not from
+inspecting the callback body.
 
 ### Control flow
 

package/dist/checker.js

@@ -1714,8 +1714,9 @@ export class Checker {
             return info.returnType;
         }
         if (expr.callee.kind === "MemberExpr") {
-            // Array.Map's result type is polymorphic (derived from the callback),
-            // which doesn't fit checkMember's fixed-signature methodInfo shape —
+            // Array.Map/Reduce's result types are polymorphic (derived from the
+            // callback and, for Reduce, the initial-value argument), which
+            // doesn't fit checkMember's fixed-signature methodInfo shape —
             // handled here instead, before the generic member/call path below.
             if (expr.callee.property === "Map") {
                 const objectType = this.checkExpression(expr.callee.object, scope, ctx);
@@ -1724,6 +1725,13 @@ export class Checker {
                     return this.checkArrayMap(expr, objectType.element, scope, ctx);
                 }
             }
+            if (expr.callee.property === "Reduce") {
+                const objectType = this.checkExpression(expr.callee.object, scope, ctx);
+                if (objectType.kind === "array") {
+                    expr.callee.isBuiltin = true;
+                    return this.checkArrayReduce(expr, objectType.element, scope, ctx);
+                }
+            }
             const { type: methodType, methodInfo } = this.checkMember(expr.callee, scope, ctx);
             if (methodInfo) {
                 this.checkArgs(expr, methodInfo.params, scope, ctx);
@@ -1911,6 +1919,48 @@ export class Checker {
             // nothing else in the type system models. Compiles to `[...arr, x]`.
             return { ...method, params: [elementType], returnType: T.arrayOf(elementType) };
         }
+        if (name === "Find") {
+            // `null` for "no match" rather than throwing/needing a sentinel —
+            // the natural fit given nullable types already exist.
+            return { ...method, params: [T.functionType([elementType], T.BOOL)], returnType: T.nullableOf(elementType) };
+        }
+        if (name === "FindIndex" || name === "IndexOf") {
+            // -1 for "not found", matching real JS — no nullable number needed,
+            // and keeps codegen a plain passthrough with no wrapping/unwrapping.
+            return { ...method, params: name === "FindIndex" ? [T.functionType([elementType], T.BOOL)] : [elementType], returnType: T.NUMBER };
+        }
+        if (name === "Includes") {
+            return { ...method, params: [elementType], returnType: T.BOOL };
+        }
+        if (name === "Sort") {
+            // No optional-parameter support in KopScript, so the comparator is
+            // always required — deliberately avoids real JS Array.sort's own
+            // well-known footgun (lexicographic-by-default on non-strings) by
+            // never having an implicit comparator to fall back to. Non-mutating,
+            // like Push — see genCall's own comment for the codegen shape.
+            return { ...method, params: [T.functionType([elementType, elementType], T.NUMBER)], returnType: T.arrayOf(elementType) };
+        }
+        if (name === "Reverse") {
+            return { ...method, params: [], returnType: T.arrayOf(elementType) };
+        }
+        if (name === "Slice") {
+            // Both bounds always required, same "no optional params" reasoning
+            // as Sort's always-required comparator.
+            return { ...method, params: [T.NUMBER, T.NUMBER], returnType: T.arrayOf(elementType) };
+        }
+        if (name === "Concat") {
+            return { ...method, params: [T.arrayOf(elementType)], returnType: T.arrayOf(elementType) };
+        }
+        if (name === "Join") {
+            // Real JS Array.join stringifies every element via implicit toString
+            // — fine for primitives (numbers/bools stringify sensibly), a real
+            // footgun for a class/interface element with no toString override
+            // ("[object Object]"), which KopScript has no way to customize.
+            // Scoped to primitive element types only, a deliberate v1 cut.
+            if (elementType.kind !== "string" && elementType.kind !== "number" && elementType.kind !== "bool")
+                return null;
+            return { ...method, params: [T.STRING], returnType: T.STRING };
+        }
         return null;
     }
     // Array.Map: `arr.Map(f)` where f: (T) => U, result: U[]. U is whatever
@@ -1939,6 +1989,34 @@ export class Checker {
         }
         return T.arrayOf(argType.returnType);
     }
+    // Array.Reduce: `arr.Reduce(reducer, initial)` where `reducer: (U, T) =>
+    // U`, matching real JS Array.prototype.reduce's own argument order.
+    // Simpler than Map's own inference — U comes directly from `initial`'s
+    // checked type, no partial-lambda-type inference needed at all.
+    checkArrayReduce(expr, elementType, scope, ctx) {
+        if (expr.args.length !== 2) {
+            this.diagnostics.error("KS4102", `Reduce expects exactly 2 arguments, got ${expr.args.length}`, expr.line, expr.col);
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        const [reducerArg, initialArg] = expr.args;
+        const accumulatorType = this.checkExpression(initialArg, scope, ctx);
+        const expectedReducerType = T.functionType([accumulatorType, elementType], accumulatorType);
+        const reducerType = this.checkExpressionExpecting(reducerArg, expectedReducerType, scope, ctx);
+        if (reducerType.kind !== "function") {
+            if (reducerType.kind !== "unknown") {
+                this.diagnostics.error("KS4103", `Reduce expects a function as its first argument, got '${T.typeToString(reducerType)}'`, reducerArg.line, reducerArg.col);
+            }
+            return accumulatorType;
+        }
+        const paramsOk = reducerType.params.length === 2 &&
+            this.isAssignableType(accumulatorType, reducerType.params[0]) &&
+            this.isAssignableType(elementType, reducerType.params[1]);
+        if (!paramsOk || !this.isAssignableType(reducerType.returnType, accumulatorType)) {
+            this.diagnostics.error("KS4104", `Reduce callback must take '(${T.typeToString(accumulatorType)}, ${T.typeToString(elementType)})' and return '${T.typeToString(accumulatorType)}', got '${T.typeToString(reducerType)}'`, reducerArg.line, reducerArg.col);
+        }
+        return accumulatorType;
+    }
     checkMember(expr, scope, ctx, isAssignTarget = false) {
         const result = this.checkMemberInner(expr, scope, ctx, isAssignTarget);
         const text = result.methodInfo
@@ -2003,12 +2081,13 @@ export class Checker {
             const method = this.arrayMethod(objectType.element, expr.property);
             if (method)
                 return { type: method.returnType, methodInfo: method };
-            // Map isn't handled here at all — its result type is polymorphic
-            // (derived from the callback passed at the call site), which doesn't
-            // fit this fixed-signature lookup. checkCall special-cases it before
-            // ever reaching checkMember, so `arr.Map(f)` works; `arr.Map` used as
-            // a bare value (not called) falls through to this error, same as an
-            // unknown member — a known v1 restriction.
+            // Map/Reduce aren't handled here at all — their result types are
+            // polymorphic (derived from the callback, and for Reduce the initial
+            // value, passed at the call site), which doesn't fit this
+            // fixed-signature lookup. checkCall special-cases both before ever
+            // reaching checkMember, so `arr.Map(f)`/`arr.Reduce(f, init)` work;
+            // either used as a bare value (not called) falls through to this
+            // error, same as an unknown member — a known v1 restriction.
             this.diagnostics.error("KS4080", `Unknown array member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }

package/dist/codegen.js

@@ -10,10 +10,15 @@ function countNewlines(text) {
 // blind syntactic rename (codegen has no type information, so this fires on
 // any member access with a matching name, string/array/user-class alike;
 // same pre-existing risk as any of the entries below, going back to the
-// original string stdlib). Map/Filter/ForEach need nothing beyond the
-// rename — the callback and everything else already codegens generically.
-// Push is handled separately in genCall, since it's non-mutating in KopScript
-// (unlike JS's own Array.push) and needs a different call shape entirely.
+// original string stdlib). Map/Filter/ForEach/Find/FindIndex/Includes/
+// IndexOf/Slice/Concat/Join/Reduce need nothing beyond the rename — the
+// callback and everything else already codegens generically, and every one
+// of these is already non-mutating in real JS, so a plain passthrough is
+// correct as-is. Push/Sort/Reverse are handled separately in genCall
+// instead: Push because it's non-mutating in KopScript (unlike JS's own
+// Array.push) and needs a different call shape entirely; Sort/Reverse for
+// the same reason — JS's own versions mutate in place, and KopScript's
+// don't, matching Push's own non-mutating convention.
 const MEMBER_METHOD_MAP = {
     Contains: "includes",
     StartsWith: "startsWith",
@@ -26,6 +31,14 @@ const MEMBER_METHOD_MAP = {
     Map: "map",
     Filter: "filter",
     ForEach: "forEach",
+    Find: "find",
+    FindIndex: "findIndex",
+    Includes: "includes",
+    IndexOf: "indexOf",
+    Slice: "slice",
+    Concat: "concat",
+    Join: "join",
+    Reduce: "reduce",
 };
 const BINARY_OP_MAP = {
     "+": "+",
@@ -461,6 +474,17 @@ export class CodeGenerator {
         if (expr.callee.kind === "MemberExpr" && expr.callee.isBuiltin && expr.callee.property === "Push" && expr.args.length === 1) {
             return `[...${this.genExpr(expr.callee.object)}, ${this.genExpr(expr.args[0])}]`;
         }
+        // Sort/Reverse are non-mutating in KopScript too, same reasoning as
+        // Push — JS's own Array.prototype.sort/reverse both mutate in place
+        // *and* return the same array, so a plain rename would silently make
+        // KopScript code alias its own "immutable" array. Copy first (`[...arr]`),
+        // then call the real JS method on the copy.
+        if (expr.callee.kind === "MemberExpr" && expr.callee.isBuiltin && expr.callee.property === "Sort" && expr.args.length === 1) {
+            return `[...${this.genExpr(expr.callee.object)}].sort(${this.genExpr(expr.args[0])})`;
+        }
+        if (expr.callee.kind === "MemberExpr" && expr.callee.isBuiltin && expr.callee.property === "Reverse" && expr.args.length === 0) {
+            return `[...${this.genExpr(expr.callee.object)}].reverse()`;
+        }
         return `${this.genExpr(expr.callee)}(${expr.args.map((a) => this.genExpr(a)).join(", ")})`;
     }
     genMember(expr) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",