kopscript 0.14.0 → 0.16.0

package/LLM.md

@@ -75,9 +75,10 @@ below). No circular `using` (compile error).
 **Does not exist**: `any`/`unknown` as a writable annotation, a `let`/`var` keyword (see
 Declarations below — there isn't one), type inference for declarations (every
 local/`const`/param/field/return type is written out explicitly), union types, tuples,
-structural/duck typing (all typing is nominal). Generics exist but are deliberately
-scoped down — see the Generics section for exactly what's NOT supported there (multiple
-type parameters, constraints, generic functions, generic inheritance).
+structural/duck typing (all typing is nominal). Generics exist and cover multiple type
+parameters, single-interface constraints, generic inheritance, and free generic functions
+— see the Generics section for exactly what's still NOT supported there (variance,
+multiple constraints per parameter, generic methods).
 
 ## Declarations
 
@@ -237,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
@@ -366,10 +382,30 @@ implemented/extended interface — never more than one) — `class Foo<T> : Box<
 IContainer<T>` is a compile error ("has more than one generic entry in its base list") even
 though either half alone would work.
 
+**Generic functions**: only free/top-level functions, never a method inside a class (a
+method still only ever uses its enclosing class's own type parameters):
+```ks
+T Identity<T>(T x) { return x; }
+number n = Identity(5);       // T inferred as number, from the argument
+string s = Identity("hi");    // T inferred as string, independently
+```
+**No explicit type argument at a call site** — `Identity<number>(5)` isn't valid syntax;
+`T` is always inferred from the actual argument types by structurally unifying each
+declared (possibly abstract) parameter type against its argument's real type — including
+through a nested generic type (`T Unwrap<T>(Box<T> b)` infers `T` from `Box<number>`) or a
+lambda argument's own explicit parameter type (`void UseCallback<T>((T) => void cb)` infers
+`T` from `(number n) => ...`). This is a real grammar constraint, not a missing feature:
+`new Box<number>(...)` disambiguates `<` from a comparison only because `new` is a distinct
+keyword context — a bare call has no such anchor, so `f<T>(x)` would be genuinely ambiguous
+with a chained `<`/`>` comparison. If no argument determines a declared type parameter, or
+two arguments would bind it to conflicting types, that's a compile error naming the
+parameter, not a syntax feature to reach for. A constrained type parameter (`T :
+IComparable`) works exactly like it does on a class — the inferred type must satisfy it,
+checked after inference succeeds.
+
 **Does not exist (v1 scope cuts, each deliberate)**:
-- **Generic functions.** `T Identity<T>(T x)` doesn't parse — only classes and interfaces
-  take type parameters, not free functions/methods themselves (a method *inside* a
-  generic class can use that class's own type parameters freely, same as any other member).
+- **Generic methods.** A class method can't introduce its own new type parameter beyond
+  its enclosing class's (generic functions are free-function-only — see above).
 - **Variance.** No `out`/`in`/covariance/contravariance — see invariance above.
 
 ## Nullable types — `T?`
@@ -541,10 +577,11 @@ Locals/params: **camelCase**. This is convention, not enforced by the compiler.
 
 ## Does not exist (don't reach for these)
 
-Generics beyond one or more type parameters (each with at most one interface constraint)
-and single-generic-base inheritance (no `T : IFoo, IBar` multi-constraints, no generic
-functions, no variance, no more than one generic entry per base list — see Generics above
-for what *is* supported) · `any`/`unknown` annotations ·
+Generics beyond one or more type parameters (each with at most one interface constraint),
+single-generic-base inheritance, and free (never method-level) generic functions with
+inference-only call sites (no `T : IFoo, IBar` multi-constraints, no explicit
+`Identity<number>(5)` type arguments, no variance, no more than one generic entry per base
+list — see Generics above for what *is* supported) · `any`/`unknown` annotations ·
 a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
 reflection · type inference on declarations · ternary expression · union/tuple types ·
 **object-literal syntax** (`{ key: value }` as a value — this doesn't exist *anywhere* in
@@ -579,9 +616,12 @@ Real, observed cases where a plausible-looking guess was wrong — not hypotheti
   dedicated rewriter, `qualifyThis`, specifically because this isn't automatic.)
 - **No `let`/`var`, ever.** Every local is `Type name = value;` — writing `let x = 5;` or a
   bare `const x = 5;` (missing the type) is a parse error, not a lenient inferred form.
-- **No generic functions.** `T Identity<T>(T x) { return x; }` doesn't parse — only classes
-  and interfaces take `<T>`. Don't reach for this even though every mainstream generic
-  language supports it.
+- **No explicit type argument at a generic function call site.** `Identity<number>(5)`
+  doesn't parse — a bare call has no keyword like `new` to disambiguate `<` from a
+  comparison, so type arguments are always inferred from the actual arguments instead.
+  Just call `Identity(5)`; if inference can't determine a type parameter, restructure the
+  call (e.g. an argument that actually mentions the type) rather than reaching for explicit
+  syntax that isn't there.
 - **Early-return doesn't narrow a nullable type.** `if (x == null) { return; } print(x.Length);`
   still errors on `x.Length` — narrowing is scope-based (an `if`/`else` block), not
   control-flow/reachability-based. Wrap the rest of the logic in the `if (x != null) { ... }`

package/README.md

@@ -22,11 +22,11 @@ LLM's context, as opposed to this README's narrative explanation.
   explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
   `public`/`protected`/`private` access model enforced at compile time.
 - **Strongly typed**: every declaration is explicitly typed and checked at compile time.
-- **Generics**: one or more invariant type parameters on classes and interfaces
-  (`class Box<T> { public T Value; }`, `class Pair<K, V> { ... }`), each optionally
-  constrained to an interface (`class Box<T : IComparable> { ... }`), plus generic
-  inheritance (`class IntBox : Box<number> { }`) — erased at codegen with zero runtime
-  cost, the same way `task<T>`/`state<T>` already are.
+- **Generics**: one or more invariant type parameters on classes, interfaces, and free
+  functions (`class Box<T> { public T Value; }`, `T Identity<T>(T x) { return x; }`), each
+  optionally constrained to an interface (`class Box<T : IComparable> { ... }`), plus
+  generic inheritance (`class IntBox : Box<number> { }`) — erased at codegen with zero
+  runtime cost, the same way `task<T>`/`state<T>` already are.
 - **Nullable types with compiler-enforced null-checking**: `T?` (`string?`, `Dog?`,
   `number[]?`) — a `T?` can't be used where a `T` is expected without an `if (x != null)`
   check first (checked statically, not just at runtime), and comparing a value that can
@@ -258,9 +258,6 @@ inside v1:
 - **Invariant.** `Box<Dog>` is **not** assignable to `Box<Animal>` even though `Dog :
   Animal`, and `Pair<number, string>` is not assignable to `Pair<string, number>` — every
   slot must match exactly, in order.
-- **No generic functions.** `T Identity<T>(T x)` isn't supported — only classes and
-  interfaces take type parameters. A method *inside* a generic class can still use that
-  class's own type parameters freely; it's just not introducing one of its own.
 
 By default a type parameter is fully unconstrained, so you can't call any member on a bare
 `T`/`K`/`V` value inside the generic class's own body — the same restriction C#/Java/
@@ -299,6 +296,24 @@ down. **v1 limit**: at most one generic entry across a whole base list (the supe
 one implemented interface — not several at once) — `class Foo<T> : Box<T>, IContainer<T>`
 is a compile error even though each half would work alone.
 
+**Free functions can be generic too** — only free/top-level functions, not class methods
+(a method inside a class still only uses its enclosing class's own type parameters, never
+introduces a new one):
+
+```ks
+T Identity<T>(T x) { return x; }
+number n = Identity(5);       // T = number, inferred from the argument
+string s = Identity("hi");    // T = string, independently
+```
+
+**No explicit type argument at the call site** — `Identity<number>(5)` isn't valid syntax;
+`T` is always inferred from the actual argument types. This is a real grammar constraint,
+not a missing feature: `new Box<number>(...)` can disambiguate `<` from a comparison only
+because `new` is a distinct keyword context — a bare call has no such anchor, so
+`f<T>(x)` would be genuinely ambiguous with a chained `<`/`>` comparison. If inference
+can't pin down a type parameter from the arguments given, that's a compile error naming the
+unresolved parameter, not a syntax feature to reach for.
+
 See `LLM.md`'s "Generics" section for the exhaustive rules if you're generating code
 against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`, `Pair<number,
 Pair<string, bool>>`) and generic interfaces used as standalone parameter types both work
@@ -661,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];
@@ -670,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
 
@@ -892,13 +931,13 @@ into your extensions folder).
 
 ## Status
 
-This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (a single
-unconstrained, invariant type parameter on classes/interfaces) have both shipped — see
-above for both. What generics deliberately doesn't cover: multiple type parameters
-(`Map<K, V>`), constraints (`T : IFoo`), generic functions, generic inheritance, and
-variance — each a real, separable extension rather than a v1 oversight. Also not yet
-supported: static auto-properties, interface properties (methods only), and nested
-functions/classes.
+This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (multiple type
+parameters, single-interface constraints, generic inheritance, and free generic functions)
+have all shipped — see above for the full "Generics" section. What generics still
+deliberately doesn't cover: variance, multiple constraints per parameter, generic methods
+(only free functions), and more than one generic entry per base list — each a real,
+separable extension rather than a v1 oversight. Also not yet supported: static
+auto-properties, interface properties (methods only), and nested functions/classes.
 
 `async`/`await`, `task<T>`, and `try`/`catch`/`finally`/`throw` are now in place (see the
 language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,

package/dist/checker.js

@@ -194,7 +194,12 @@ export class Checker {
             this.checkClassBody(c);
     }
     registerExternFunction(decl) {
+        // extern functions never take a type parameter of their own in v1 —
+        // generic functions (see registerFunction) are a real-function-only
+        // feature; an extern binding always describes a concrete signature.
         this.functions.set(decl.name, {
+            typeParams: [],
+            typeParamConstraints: [],
             params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
             returnType: this.resolveType(decl.returnType, decl.line, decl.col),
         });
@@ -504,6 +509,68 @@ export class Checker {
                 return type;
         }
     }
+    // The reverse of substituteTypeParams: derives bindings *from* matching a
+    // generic function's declared (abstract) parameter type against one real
+    // argument's actual (concrete) type, instead of substituting bindings
+    // *into* a type. Structural unification, same recursive shape as
+    // substituteTypeParams/typesEqual — whenever `declared` is a TypeParamType
+    // for one of `typeParamNames`, records `bindings.set(name, actual)` the
+    // first time it's seen; a later argument that would bind the same name to
+    // a genuinely different type is recorded in `conflicts` instead of
+    // silently overwriting (see checkGenericFunctionCall's own error for
+    // that). A structural mismatch elsewhere (e.g. declared is `T[]` but
+    // actual isn't an array at all) simply infers nothing from that
+    // position — the normal post-substitution assignability check catches
+    // the real type error afterward, with a clearer message than unification
+    // failing silently here would give.
+    inferTypeParamBindings(declared, actual, typeParamNames, bindings, conflicts) {
+        if (declared.kind === "typeParam" && typeParamNames.has(declared.name)) {
+            const existing = bindings.get(declared.name);
+            if (existing) {
+                if (!T.typesEqual(existing, actual))
+                    conflicts.set(declared.name, actual);
+            }
+            else {
+                bindings.set(declared.name, actual);
+            }
+            return;
+        }
+        if (declared.kind === "array" && actual.kind === "array") {
+            this.inferTypeParamBindings(declared.element, actual.element, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "nullable") {
+            const actualInner = actual.kind === "nullable" ? actual.inner : actual;
+            this.inferTypeParamBindings(declared.inner, actualInner, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "task" && actual.kind === "task") {
+            this.inferTypeParamBindings(declared.resultType, actual.resultType, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "state" && actual.kind === "state") {
+            this.inferTypeParamBindings(declared.valueType, actual.valueType, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if ((declared.kind === "class" || declared.kind === "interface") && declared.kind === actual.kind && declared.name === actual.name) {
+            const declaredArgs = declared.typeArgs ?? [];
+            const actualArgs = actual.typeArgs ?? [];
+            declaredArgs.forEach((d, i) => {
+                if (actualArgs[i])
+                    this.inferTypeParamBindings(d, actualArgs[i], typeParamNames, bindings, conflicts);
+            });
+            return;
+        }
+        if (declared.kind === "function" && actual.kind === "function") {
+            declared.params.forEach((d, i) => {
+                if (actual.params[i])
+                    this.inferTypeParamBindings(d, actual.params[i], typeParamNames, bindings, conflicts);
+            });
+            this.inferTypeParamBindings(declared.returnType, actual.returnType, typeParamNames, bindings, conflicts);
+        }
+        // Anything else (primitive/enum/void/unknown, or a structural
+        // mismatch) has nothing to unify — no-op.
+    }
     // Builds the bindings map for a generic reference (a `ClassType`/
     // `InterfaceType`'s own `typeArgs`, zipped against its declared
     // `typeParams`) — the "own bindings" every member-lookup/conformance
@@ -879,10 +946,18 @@ export class Checker {
         }
     }
     registerFunction(decl) {
-        const params = decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col));
-        const returnType = this.resolveType(decl.returnType, decl.line, decl.col);
-        this.functions.set(decl.name, { params, returnType });
-        this.recordHover(decl.line, decl.col, `function ${decl.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
+        const { params, returnType } = this.withTypeParamsInScope(decl.typeParams, () => ({
+            params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
+            returnType: this.resolveType(decl.returnType, decl.line, decl.col),
+        }));
+        this.functions.set(decl.name, {
+            typeParams: decl.typeParams.map((p) => p.name),
+            typeParamConstraints: decl.typeParams.map((p) => p.constraint),
+            params,
+            returnType,
+        });
+        const nameWithTypeParam = decl.typeParams.length > 0 ? `${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : decl.name;
+        this.recordHover(decl.line, decl.col, `function ${nameWithTypeParam}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
     }
     isSubclass(sub, sup) {
         let current = sub;
@@ -1082,11 +1157,17 @@ export class Checker {
         this.checkStatement(stmt, scope, { returnType: T.VOID, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: true });
     }
     checkFunctionBody(decl, parentScope) {
-        const info = this.functions.get(decl.name);
-        const scope = parentScope.child();
-        decl.params.forEach((p, i) => scope.declare(p.name, info.params[i], false));
-        const returnType = this.resolveBodyReturnType(info.returnType, decl.isAsync, decl.line, decl.col);
-        this.checkBlock(decl.body, scope, { returnType, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: decl.isAsync });
+        // Same withTypeParamsInScope treatment checkClassBody gives a generic
+        // class's own method bodies — without it, a generic function's type
+        // parameter would resolve in its declared signature but not inside a
+        // local declaration/lambda written in its own body.
+        this.withTypeParamsInScope(decl.typeParams, () => {
+            const info = this.functions.get(decl.name);
+            const scope = parentScope.child();
+            decl.params.forEach((p, i) => scope.declare(p.name, info.params[i], false));
+            const returnType = this.resolveBodyReturnType(info.returnType, decl.isAsync, decl.line, decl.col);
+            this.checkBlock(decl.body, scope, { returnType, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: decl.isAsync });
+        });
     }
     checkClassBody(decl) {
         // Constructor/method *bodies* run in this same scope registerClass used
@@ -1626,12 +1707,16 @@ export class Checker {
                 return T.UNKNOWN;
             }
             this.recordHover(expr.callee.line, expr.callee.col, `function ${expr.callee.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
+            if (info.typeParams.length > 0) {
+                return this.checkGenericFunctionCall(expr, expr.callee.name, info, scope, ctx);
+            }
             this.checkArgs(expr, info.params, scope, ctx);
             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);
@@ -1640,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);
@@ -1678,6 +1770,50 @@ export class Checker {
             }
         });
     }
+    // A generic function call has no explicit type-argument syntax (see
+    // README's "Generics" — a real grammar-ambiguity reason, `f<T>(x)` is
+    // indistinguishable from a chained comparison with no keyword like `new`
+    // to disambiguate it), so every type parameter is inferred from the
+    // actual argument types instead. Checks argument count first (an arity
+    // mismatch would make inference itself meaningless), infers bindings by
+    // unifying each declared (abstract) parameter type against its actual
+    // argument's real type (see inferTypeParamBindings), then re-runs the
+    // normal assignability check with the now-concrete substituted parameter
+    // types — catching anything structural unification alone wouldn't (e.g.
+    // an argument assignable to, but not identical to, its inferred slot).
+    checkGenericFunctionCall(expr, functionName, info, scope, ctx) {
+        if (expr.args.length !== info.params.length) {
+            this.diagnostics.error("KS4098", `Expected ${info.params.length} argument(s), got ${expr.args.length}`, expr.line, expr.col);
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        const actualArgTypes = expr.args.map((a) => this.checkExpression(a, scope, ctx));
+        const typeParamNames = new Set(info.typeParams);
+        const bindings = new Map();
+        const conflicts = new Map();
+        info.params.forEach((declared, i) => this.inferTypeParamBindings(declared, actualArgTypes[i], typeParamNames, bindings, conflicts));
+        for (const [name, conflictingType] of conflicts) {
+            this.diagnostics.error("KS4099", `Type parameter '${name}' inferred as both '${T.typeToString(bindings.get(name))}' and '${T.typeToString(conflictingType)}' from different arguments — conflicting types`, expr.line, expr.col);
+        }
+        const unresolved = info.typeParams.filter((name) => !bindings.has(name));
+        if (unresolved.length > 0) {
+            this.diagnostics.error("KS4100", `Cannot infer type parameter${unresolved.length === 1 ? "" : "s"} '${unresolved.join("', '")}' for '${functionName}' — no argument determines ${unresolved.length === 1 ? "it" : "them"}`, expr.line, expr.col);
+            return T.UNKNOWN;
+        }
+        info.typeParams.forEach((name, i) => {
+            const constraint = info.typeParamConstraints[i];
+            if (constraint)
+                this.checkConstraintSatisfied(bindings.get(name), constraint, name, expr.line, expr.col);
+        });
+        const substitutedParams = info.params.map((p) => this.substituteTypeParams(p, bindings));
+        expr.args.forEach((arg, i) => {
+            const expected = substitutedParams[i];
+            if (!this.isAssignableType(actualArgTypes[i], expected)) {
+                this.diagnostics.error("KS4101", `Argument ${i + 1} has type '${T.typeToString(actualArgTypes[i])}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
+            }
+        });
+        return this.substituteTypeParams(info.returnType, bindings);
+    }
     checkNew(expr, scope, ctx) {
         if (this.interfaces.has(expr.className)) {
             this.diagnostics.error("KS4066", `Cannot instantiate interface '${expr.className}'`, expr.line, expr.col);
@@ -1783,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
@@ -1811,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
@@ -1875,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/dist/parser.js

@@ -198,14 +198,24 @@ export class Parser {
         const type = this.parseType();
         const nameTok = this.consume(TokenKind.Identifier, "Expected name");
         const name = nameTok.lexeme;
+        // `T Identity<T>(T x) { ... }` — a free function's own type-param list,
+        // between its name and `(`. Only meaningful for the function branch
+        // below; a local/top-level variable declaration never has `<` right
+        // after its name, so trying this first costs nothing in that case
+        // (parseTypeParamList returns immediately without consuming anything
+        // when `<` isn't there).
+        const typeParams = this.parseTypeParamList();
         if (this.check(TokenKind.LParen)) {
             const params = this.parseParamList();
             const body = this.parseBlock();
-            return { kind: "FunctionDecl", isExported, isAsync, name, params, returnType: type, body, line: start.line, col: start.col };
+            return { kind: "FunctionDecl", isExported, isAsync, name, typeParams, params, returnType: type, body, line: start.line, col: start.col };
         }
         if (isAsync) {
             this.diagnostics.error("KS2006", "'async' cannot modify a variable declaration", start.line, start.col);
         }
+        if (typeParams.length > 0) {
+            this.diagnostics.error("KS2023", "A type parameter list is only allowed on a function declaration", start.line, start.col);
+        }
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
         this.consume(TokenKind.Semicolon, "Expected ';' after variable declaration");

package/dist/printer.js

@@ -208,7 +208,8 @@ export class Printer {
     printFunction(decl, indent) {
         const pad = indentStr(indent);
         const prefix = `${decl.isExported ? "" : "private "}${decl.isAsync ? "async " : ""}`;
-        return `${pad}${prefix}${this.printType(decl.returnType)} ${decl.name}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
+        const nameWithTypeParam = this.printTypeParamName(decl);
+        return `${pad}${prefix}${this.printType(decl.returnType)} ${nameWithTypeParam}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
     }
     // Canonical member order: fields, then properties, then the constructor,
     // then methods — regardless of how the original source interleaved them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.14.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",