kopscript 0.3.0 → 0.4.0

package/LLM.md

@@ -56,11 +56,14 @@ below). No circular `using` (compile error).
 | `task` / `task<T>` | see Async below |
 | `state<T>` | see Reactive state below |
 | `T?` | nullable — see Nullable types below |
+| `Box<T>` | a user-declared generic class/interface — see Generics below |
 
-**Does not exist**: generics (no `class Foo<T>`, no `T Resolve<T>()`), `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).
+**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).
 
 ## Declarations
 
@@ -116,6 +119,8 @@ Dog d = new Dog("Rex");
   the interface in the base list and provide matching public methods, checked at compile time.
 - No nested classes/functions.
 - No multiple inheritance (at most one class in the base list; the rest must be interfaces).
+- `class Box<T> { ... }` — a single type parameter is allowed; see Generics below for the
+  full (deliberately scoped-down) rules.
 
 ### Interfaces
 
@@ -126,6 +131,9 @@ interface IShape {
 interface INamedShape : IShape { // interfaces can extend other interfaces (not classes)
   string GetName();
 }
+interface IContainer<T> {      // interfaces take a single type parameter too — see Generics
+  T Get();
+}
 ```
 
 ### Enums
@@ -250,8 +258,54 @@ count.Value = count.Value + 1;
 count.Subscribe((number v) => { ... }); // called on every future .Value assignment
 ```
 
-Not a generic type parameter — `state<T>` is one of exactly two hardcoded parametrized
-forms in the type system (the other is `task<T>`).
+Not a use of user-declared generics (see below) — `state<T>` is one of exactly two
+hardcoded parametrized forms in the type system (the other is `task<T>`), each with only
+ever one built-in meaning, unlike a real generic class/interface.
+
+## Generics — a single type parameter on classes/interfaces
+
+```ks
+class Box<T> {
+  public T Value;
+  constructor(T v) { this.Value = v; }
+  public T Get() { return this.Value; }
+}
+
+Box<number> nb = new Box<number>(5);   // type argument required on both the type AND `new`
+Box<string> sb = new Box<string>("hi");
+print(nb.Get());                        // 5
+```
+
+One unconstrained, invariant type parameter per class/interface — the whole feature.
+Erased at codegen (JS has no generics either; `Box<number>` and `Box<string>` both
+compile to the exact same plain `class Box`), so there's no runtime cost and no way to
+inspect `T` at runtime.
+
+**Rules:**
+- The type argument is **required everywhere** a generic type is named — on the variable
+  type (`Box<number>`) and separately on `new` (`new Box<number>(...)`); a bare `Box` (no
+  argument) is a compile error, not "any"/inferred.
+- **Invariant**: `Box<Dog>` is not assignable to `Box<Animal>` even if `Dog : Animal` —
+  type arguments must match exactly, not just be compatible.
+- Nesting works: `Box<Box<number>>`, `Box<number[]>`, `Box<number>?`, `Box<number>?[]`.
+- Inside the class/interface's own body, `T` is fully abstract — you can store it, return
+  it, pass it around, but (unconstrained) you **cannot call any member on a bare `T`
+  value** (`this.value.Foo()` is a compile error: "Cannot access member 'Foo' on type
+  'T'"). This is correct, not a bug — same as an unconstrained type parameter in
+  C#/Java/TypeScript.
+
+**Does not exist (v1 scope cuts, each deliberate)**:
+- **Generic functions.** `T Identity<T>(T x)` doesn't parse — only classes and interfaces
+  take a type parameter, not free functions/methods themselves (a method *inside* a
+  generic class can use that class's own `T` freely, same as any other member).
+- **Multiple type parameters.** No `Map<K, V>` — exactly one `<T>` or none.
+- **Constraints.** No `T : IComparable` — a type parameter is always fully unconstrained,
+  which is why you can't call members on a bare `T` (see above).
+- **Generic inheritance.** A class/interface's base list can only name a *non-generic*
+  type — `class Foo : Box<number>` and even `class Foo<T> : SomeGenericBase<T>` are both
+  compile errors ("cannot extend/implement generic type '...' — not supported in v1"). A
+  generic class/interface can still extend/implement ordinary non-generic bases normally.
+- **Variance.** No `out`/`in`/covariance/contravariance — see invariance above.
 
 ## Nullable types — `T?`
 
@@ -328,6 +382,27 @@ KopScript-declared name exactly. Extern class members use real JS member names v
 (camelCase, no rename mechanism). No inheritance modeling between two `extern class`
 declarations — each stands alone.
 
+**Never write `async` on an extern function/method signature** — declare its return type
+as `task`/`task<T>` directly (`task<string> text();`, not `async task<string> text();`).
+`async` only means something for a *body* the checker validates (legalizing `await`
+inside it, checking `return` against the unwrapped type); an extern signature has no
+body, so the keyword is simply invalid there — a parse error, not a no-op. This applies
+equally to a top-level `extern` function and an `extern class` method signature.
+
+`jsName` (the `as "..."` string) can be a dotted path, not just a bare identifier — e.g.
+`as "JSON.parse"` — since it's spliced directly into `globalThis.<jsName>` for an
+ambient binding. This is the supported way to get a *typed* (unchecked, trust-based)
+JSON value: describe the shape as its own `extern class`, then declare a parse function
+for it: `extern MyShape ParseIt(string json) as "JSON.parse";` — calling `ParseIt(text)`
+returns whatever `JSON.parse` actually parsed, typed as `MyShape` with zero runtime
+verification (the same trust model as every other `extern`).
+
+An `extern class` reachable from a real npm package — not same-project `using`, which
+only resolves relative `.ks` paths — is how KopScript consumes *any* JS dependency,
+including another KopScript-authored package published as JS (e.g. Kopular): describe
+exactly the members used, from that package's real module specifier. See Kopular's own
+`LLM.md`/README for a live example (`Component`, `Router`, `Http`, ...).
+
 ## `raw string` — compile-time file embedding
 
 ```ks
@@ -354,6 +429,11 @@ Locals/params: **camelCase**. This is convention, not enforced by the compiler.
 Generics · `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
+the grammar, not just as a type; a JS API whose signature needs one — `fetch`'s options
+argument, `addEventListener`'s options object, etc. — can't be called directly from
+KopScript at all; see Kopular's `http.ks`/`http_runtime.js` for the one established
+workaround, a small hand-written JS shim, not a language feature) ·
 structural typing · multiple class inheritance ·
 nested classes/functions · method overloading · default/optional parameters · varargs ·
 static properties with accessors (static fields only) · interface properties (interface

package/README.md

@@ -22,6 +22,9 @@ 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**: a single, unconstrained, invariant type parameter on classes and
+  interfaces (`class Box<T> { public T Value; }`) — 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
@@ -204,6 +207,49 @@ void Announce(ISpeaker s) {
 }
 ```
 
+### Generics
+
+Classes and interfaces can take a single type parameter:
+
+```ks
+class Box<T> {
+  public T Value;
+  constructor(T v) { this.Value = v; }
+  public T Get() { return this.Value; }
+}
+
+Box<number> nb = new Box<number>(5);
+Box<string> sb = new Box<string>("hi");
+print(nb.Get());   // 5
+```
+
+The type argument is required everywhere the generic type is named — on the variable's
+declared type *and* separately on `new` (`Box<number> nb = new Box<number>(5);`, not
+just one or the other). Generics are erased at codegen exactly like `task<T>`/`state<T>`
+already are — `Box<number>` and `Box<string>` compile to the identical plain `class Box`,
+so there's no runtime cost.
+
+This is deliberately the smallest useful slice of generics, not a scaled-down promise of
+more later inside v1:
+
+- **One type parameter, invariant, unconstrained.** No `Map<K, V>` (multiple parameters),
+  no `T : ISomething` (constraints) — and because `T` is fully unconstrained, you can't
+  call any member on a bare `T` value inside the generic class's own body (that's correct
+  behavior, the same restriction C#/Java/TypeScript put on an unconstrained parameter, not
+  a bug). Invariant means `Box<Dog>` is **not** assignable to `Box<Animal>` even though
+  `Dog : Animal` — type arguments must match exactly.
+- **No generic functions.** `T Identity<T>(T x)` isn't supported — only classes and
+  interfaces take a type parameter. A method *inside* a generic class can still use that
+  class's own `T` freely; it's just not introducing a type parameter of its own.
+- **No generic inheritance.** A class or interface's base list can only name a
+  *non-generic* type. `class Foo : Box<number>` and `class Foo<T> : SomeBase<T>` are both
+  compile errors — a generic class can still extend/implement ordinary non-generic bases
+  normally, it just can't be the one on either side of a generic base relationship.
+
+See `LLM.md`'s "Generics" section for the exhaustive rules if you're generating code
+against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`) and generic
+interfaces used as standalone parameter types both work and are covered there.
+
 ### Enums
 
 ```ks
@@ -521,8 +567,9 @@ foreach (number item in items) {
 ### Types (v1 scope)
 
 `number`, `string`, `bool`, `void`, `T[]` (arrays), class types, interface types, enum
-types, function types (`(T, ...) => R`), and nullable types (`T?`, with `null` and
-compiler-enforced null-checking — see "Nullable types" below). No generics yet.
+types, function types (`(T, ...) => R`), nullable types (`T?`, with `null` and
+compiler-enforced null-checking — see "Nullable types" below), and a single type
+parameter on classes/interfaces (`Box<T>` — see "Generics" above).
 
 ### Nullable types — `T?`
 
@@ -649,15 +696,13 @@ into your extensions folder).
 
 ## Status
 
-This is a v1 / hobby-project scope. Nullable types (`T?`) shipped — see above. Not yet
-supported: generics, static auto-properties, interface properties (methods only), and
-nested functions/classes. Generics in particular is a substantially bigger undertaking
-than everything else here — it touches the type system's core (type parameters,
-variance, constraint checking) rather than being an additive feature, so it's
-deliberately left for a dedicated future pass rather than bolted on. Nullable types
-turned out to fit that "additive feature" shape after all: no variance or constraint
-solving involved, so it landed as a normal-sized change — a lesson for scoping generics
-itself, not evidence generics will be similarly sized.
+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.
 
 `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

@@ -56,6 +56,12 @@ export class Checker {
         this.functions = new Map();
         this.externValues = new Map();
         this.namedTypes = new Map();
+        // className/interfaceName -> its type parameter's name (e.g. "Box" -> "T"),
+        // for every generic class/interface — populated up front, before any type
+        // resolution runs, specifically so a forward reference (class A's field
+        // referencing generic class B, declared later in the same file) still
+        // resolves B's genericity correctly. See resolveType/validateGenericArity.
+        this.genericTypeParams = new Map();
         this.importedNames = new Set();
         this.rawContents = new Map();
         this.hoverEntries = [];
@@ -65,10 +71,16 @@ export class Checker {
             this.namedTypes.set(name, kind);
             this.importedNames.add(name);
         }
-        for (const [name, info] of this.imports.classes)
+        for (const [name, info] of this.imports.classes) {
             this.classes.set(name, info);
-        for (const [name, info] of this.imports.interfaces)
+            if (info.typeParam)
+                this.genericTypeParams.set(name, info.typeParam);
+        }
+        for (const [name, info] of this.imports.interfaces) {
             this.interfaces.set(name, info);
+            if (info.typeParam)
+                this.genericTypeParams.set(name, info.typeParam);
+        }
         for (const [name, info] of this.imports.enums)
             this.enums.set(name, info);
         for (const [name, info] of this.imports.functions) {
@@ -96,6 +108,12 @@ export class Checker {
             this.namedTypes.set(e.name, "enum");
         for (const c of externClassDecls)
             this.namedTypes.set(c.name, "class");
+        for (const c of classDecls)
+            if (c.typeParam)
+                this.genericTypeParams.set(c.name, c.typeParam);
+        for (const i of interfaceDecls)
+            if (i.typeParam)
+                this.genericTypeParams.set(i.name, i.typeParam);
         for (const e of enumDecls)
             this.registerEnum(e);
         for (const i of interfaceDecls)
@@ -172,6 +190,7 @@ export class Checker {
         const ownCtorParams = decl.hasConstructor ? decl.ctorParams.map((p) => this.resolveType(p.type, decl.line, decl.col)) : null;
         this.classes.set(decl.name, {
             name: decl.name,
+            typeParam: null,
             superclass: null,
             interfaces: [],
             fields,
@@ -312,11 +331,111 @@ export class Checker {
         });
         if (!resolved) {
             const name = node.kind === "NamedType" ? node.name : "[]";
-            this.diagnostics.error(`Unknown type '${name}'`, line, col);
+            if (name !== "[]" && this.genericTypeParams.has(name) && !node.typeArgs) {
+                this.diagnostics.error(`Generic type '${name}' requires a type argument (e.g. '${name}<T>')`, line, col);
+            }
+            else {
+                this.diagnostics.error(`Unknown type '${name}'`, line, col);
+            }
             return T.UNKNOWN;
         }
+        this.validateGenericArity(resolved, line, col);
         return resolved;
     }
+    // resolveTypeNode mechanically attaches whatever type argument a
+    // NamedType node happened to carry, without knowing which names are
+    // actually declared generic (that's checker state, not something the
+    // pure type-resolution function has access to) — this is the other half:
+    // walking the successfully-resolved type looking for a class/interface
+    // whose generic-ness doesn't match whether it got a type argument.
+    validateGenericArity(type, line, col) {
+        switch (type.kind) {
+            case "array":
+                this.validateGenericArity(type.element, line, col);
+                return;
+            case "function":
+                type.params.forEach((p) => this.validateGenericArity(p, line, col));
+                this.validateGenericArity(type.returnType, line, col);
+                return;
+            case "task":
+                this.validateGenericArity(type.resultType, line, col);
+                return;
+            case "state":
+                this.validateGenericArity(type.valueType, line, col);
+                return;
+            case "nullable":
+                this.validateGenericArity(type.inner, line, col);
+                return;
+            case "class":
+            case "interface": {
+                const isGeneric = this.genericTypeParams.has(type.name);
+                if (isGeneric && !type.typeArg) {
+                    this.diagnostics.error(`Generic type '${type.name}' requires a type argument (e.g. '${type.name}<T>')`, line, col);
+                }
+                else if (!isGeneric && type.typeArg) {
+                    this.diagnostics.error(`Type '${type.name}' is not generic — it doesn't take a type argument`, line, col);
+                }
+                if (type.typeArg)
+                    this.validateGenericArity(type.typeArg, line, col);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    // Temporarily makes `name` (a class/interface's own type parameter, e.g.
+    // "T") resolve as a TypeParamType, for the duration of `fn` — used only
+    // while registering that class/interface's own declaration (fields,
+    // methods, ctor params), so `T Value;` resolves correctly. Scoped this
+    // narrowly (set, run, delete/restore) rather than left in `namedTypes`
+    // permanently, since it's only ever meaningful inside that one
+    // declaration's own body.
+    withTypeParamInScope(typeParam, fn) {
+        if (!typeParam)
+            return fn();
+        const previous = this.namedTypes.get(typeParam);
+        this.namedTypes.set(typeParam, "typeParam");
+        try {
+            return fn();
+        }
+        finally {
+            if (previous === undefined)
+                this.namedTypes.delete(typeParam);
+            else
+                this.namedTypes.set(typeParam, previous);
+        }
+    }
+    // Replaces every occurrence of the class/interface's own type parameter
+    // (by name) inside `type` with `arg` — the substitution step that turns
+    // Box<T>'s abstractly-stored field type `T` into `number` when someone
+    // actually asks about `Box<number>.Value`. A type with no occurrence of
+    // `paramName` anywhere in it is returned unchanged (including every
+    // non-generic type, the overwhelming majority).
+    substituteTypeParam(type, paramName, arg) {
+        switch (type.kind) {
+            case "typeParam":
+                return type.name === paramName ? arg : type;
+            case "array":
+                return T.arrayOf(this.substituteTypeParam(type.element, paramName, arg));
+            case "nullable":
+                return T.nullableOf(this.substituteTypeParam(type.inner, paramName, arg));
+            case "task":
+                return T.taskType(this.substituteTypeParam(type.resultType, paramName, arg));
+            case "state":
+                return T.stateType(this.substituteTypeParam(type.valueType, paramName, arg));
+            case "function":
+                return T.functionType(type.params.map((p) => this.substituteTypeParam(p, paramName, arg)), this.substituteTypeParam(type.returnType, paramName, arg));
+            // A nested generic's own type argument can itself mention the outer
+            // T (`Box<T[]>`'s field being List<T> — a v1 corner case, but cheap
+            // to handle correctly): substitute inside it too.
+            case "class":
+                return type.typeArg ? T.classType(type.name, this.substituteTypeParam(type.typeArg, paramName, arg)) : type;
+            case "interface":
+                return type.typeArg ? T.interfaceType(type.name, this.substituteTypeParam(type.typeArg, paramName, arg)) : type;
+            default:
+                return type;
+        }
+    }
     registerEnum(decl) {
         const members = new Map();
         decl.members.forEach((name, index) => {
@@ -330,22 +449,29 @@ export class Checker {
         this.recordHover(decl.line, decl.col, `enum ${decl.name}`);
     }
     registerInterface(decl) {
-        const methods = decl.methods.map((m) => {
+        const methods = this.withTypeParamInScope(decl.typeParam, () => decl.methods.map((m) => {
             const params = m.params.map((p) => this.resolveType(p.type, m.line, m.col));
             const returnType = this.resolveType(m.returnType, m.line, m.col);
             this.recordHover(m.nameLine, m.nameCol, `${m.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
             return { name: m.name, params, returnType };
-        });
+        }));
         const bases = [];
         for (const baseName of decl.baseList) {
             if (this.namedTypes.get(baseName) !== "interface") {
                 this.diagnostics.error(`Interface '${decl.name}' can only extend other interfaces (unknown interface '${baseName}')`, decl.line, decl.col);
                 continue;
             }
+            // v1 generics can't appear in a base list at all — only as a
+            // standalone type (field/param/return/local, `new Box<T>()`). A
+            // class/interface always implements/extends a *bare* name.
+            if (this.genericTypeParams.has(baseName)) {
+                this.diagnostics.error(`Interface '${decl.name}' cannot extend generic interface '${baseName}' — not supported in v1`, decl.line, decl.col);
+                continue;
+            }
             bases.push(baseName);
         }
-        this.interfaces.set(decl.name, { name: decl.name, bases, methods });
-        this.recordHover(decl.line, decl.col, `interface ${decl.name}`);
+        this.interfaces.set(decl.name, { name: decl.name, typeParam: decl.typeParam, bases, methods });
+        this.recordHover(decl.line, decl.col, decl.typeParam ? `interface ${decl.name}<${decl.typeParam}>` : `interface ${decl.name}`);
     }
     checkInterfaceHierarchy(decl) {
         const info = this.interfaces.get(decl.name);
@@ -388,38 +514,48 @@ export class Checker {
         return info.bases.some((b) => this.interfaceExtends(b, sup));
     }
     registerClass(decl) {
-        this.recordHover(decl.line, decl.col, `class ${decl.name}`);
-        const fields = new Map();
-        const staticFields = new Map();
-        for (const f of decl.fields) {
-            const info = { type: this.resolveType(f.type, f.line, f.col), visibility: f.visibility, hasSetter: true };
-            this.recordHover(f.nameLine, f.nameCol, `${f.name}: ${T.typeToString(info.type)}`);
-            (f.isStatic ? staticFields : fields).set(f.name, info);
-        }
-        for (const p of decl.properties) {
-            const type = this.resolveType(p.type, p.line, p.col);
-            this.recordHover(p.nameLine, p.nameCol, `${p.name}: ${T.typeToString(type)}`);
-            fields.set(p.name, { type, visibility: p.visibility, hasSetter: p.hasSetter });
-        }
-        const methods = new Map();
-        const staticMethods = new Map();
-        for (const m of decl.methods) {
-            const info = {
-                params: m.params.map((p) => this.resolveType(p.type, m.line, m.col)),
-                returnType: this.resolveType(m.returnType, m.line, m.col),
-                visibility: m.visibility,
-                isVirtual: m.isVirtual,
-                isOverride: m.isOverride,
-            };
-            this.recordHover(m.nameLine, m.nameCol, `${m.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
-            (m.isStatic ? staticMethods : methods).set(m.name, info);
-        }
-        const ownCtorParams = decl.constructor
-            ? decl.constructor.params.map((p) => this.resolveType(p.type, decl.constructor.line, decl.constructor.col))
-            : null;
+        this.recordHover(decl.line, decl.col, decl.typeParam ? `class ${decl.name}<${decl.typeParam}>` : `class ${decl.name}`);
+        const { fields, staticFields, methods, staticMethods, ownCtorParams } = this.withTypeParamInScope(decl.typeParam, () => {
+            const fields = new Map();
+            const staticFields = new Map();
+            for (const f of decl.fields) {
+                const info = { type: this.resolveType(f.type, f.line, f.col), visibility: f.visibility, hasSetter: true };
+                this.recordHover(f.nameLine, f.nameCol, `${f.name}: ${T.typeToString(info.type)}`);
+                (f.isStatic ? staticFields : fields).set(f.name, info);
+            }
+            for (const p of decl.properties) {
+                const type = this.resolveType(p.type, p.line, p.col);
+                this.recordHover(p.nameLine, p.nameCol, `${p.name}: ${T.typeToString(type)}`);
+                fields.set(p.name, { type, visibility: p.visibility, hasSetter: p.hasSetter });
+            }
+            const methods = new Map();
+            const staticMethods = new Map();
+            for (const m of decl.methods) {
+                const info = {
+                    params: m.params.map((p) => this.resolveType(p.type, m.line, m.col)),
+                    returnType: this.resolveType(m.returnType, m.line, m.col),
+                    visibility: m.visibility,
+                    isVirtual: m.isVirtual,
+                    isOverride: m.isOverride,
+                };
+                this.recordHover(m.nameLine, m.nameCol, `${m.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
+                (m.isStatic ? staticMethods : methods).set(m.name, info);
+            }
+            const ownCtorParams = decl.constructor
+                ? decl.constructor.params.map((p) => this.resolveType(p.type, decl.constructor.line, decl.constructor.col))
+                : null;
+            return { fields, staticFields, methods, staticMethods, ownCtorParams };
+        });
         let superclass = null;
         const interfaces = [];
         for (const baseName of decl.baseList) {
+            // v1 generics can't appear in a base list at all — only as a
+            // standalone type (field/param/return/local, `new Box<T>()`). A
+            // class always extends/implements a *bare* name.
+            if (this.genericTypeParams.has(baseName)) {
+                this.diagnostics.error(`Class '${decl.name}' cannot extend/implement generic type '${baseName}' — not supported in v1`, decl.line, decl.col);
+                continue;
+            }
             const kind = this.namedTypes.get(baseName);
             if (kind === "class") {
                 if (superclass !== null) {
@@ -438,6 +574,7 @@ export class Checker {
         }
         this.classes.set(decl.name, {
             name: decl.name,
+            typeParam: decl.typeParam,
             superclass,
             interfaces,
             fields,
@@ -649,6 +786,14 @@ export class Checker {
         if (from.kind === "nullable")
             return false;
         if (to.kind === "interface") {
+            // Invariant generics: v1 has no generic inheritance (a class/interface
+            // base list can only name a non-generic type — see registerClass/
+            // registerInterface), so the *only* way `from`'s interface name can
+            // ever match `to`'s is a literal same-interface reference (never a
+            // distinct generic instantiation implementing another) — still worth
+            // checking the type argument actually matches, same as the class case.
+            if (from.kind === "interface" && from.name === to.name)
+                return this.typeArgsMatch(from, to);
             if (from.kind === "class")
                 return this.classImplementsInterface(from.name, to.name);
             if (from.kind === "interface")
@@ -656,13 +801,26 @@ export class Checker {
             return false;
         }
         if (from.kind === "class" && to.kind === "class") {
-            return from.name === to.name || this.isSubclass(from.name, to.name);
+            if (from.name === to.name)
+                return this.typeArgsMatch(from, to);
+            return this.isSubclass(from.name, to.name);
         }
         if (from.kind === "array" && to.kind === "array") {
             return this.isAssignableType(from.element, to.element);
         }
         return T.typesEqual(from, to);
     }
+    // Invariant: Box<number> and Box<string> are unrelated, and so is a
+    // generic type referenced with vs. without its type argument (the latter
+    // only ever arises from an arity error already diagnosed at the
+    // reference site — see validateGenericArity).
+    typeArgsMatch(a, b) {
+        if (!a.typeArg && !b.typeArg)
+            return true;
+        if (!a.typeArg || !b.typeArg)
+            return false;
+        return T.typesEqual(a.typeArg, b.typeArg);
+    }
     // ---------- top-level ----------
     // Validates that `isAsync` and the declared return type agree — `async`
     // requires `task`/`task<T>`, and `task`/`task<T>` requires `async` (there's
@@ -1225,6 +1383,7 @@ export class Checker {
             if (expr.callee.property === "Map") {
                 const objectType = this.checkExpression(expr.callee.object, scope, ctx);
                 if (objectType.kind === "array") {
+                    expr.callee.isBuiltin = true; // see checkMemberInner's string/array branches
                     return this.checkArrayMap(expr, objectType.element, scope, ctx);
                 }
             }
@@ -1283,8 +1442,31 @@ export class Checker {
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
-        this.recordHover(expr.line, expr.col, `class ${expr.className}`);
-        const ctorParams = this.lookupCtorParams(expr.className);
+        let typeArg;
+        if (info.typeParam && !expr.typeArgs) {
+            this.diagnostics.error(`Generic class '${expr.className}' requires a type argument (e.g. 'new ${expr.className}<T>(...)')`, expr.line, expr.col);
+            // Abstractly-typed (T-containing) ctor params, un-substitutable
+            // without a real type argument, would otherwise cascade into a
+            // confusing "expected 'T'" error on every argument — one clear error
+            // beats that pile-on.
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        if (!info.typeParam && expr.typeArgs) {
+            this.diagnostics.error(`Class '${expr.className}' is not generic — it doesn't take a type argument`, expr.line, expr.col);
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        if (info.typeParam && expr.typeArgs) {
+            typeArg = this.resolveType(expr.typeArgs[0], expr.line, expr.col);
+        }
+        this.recordHover(expr.line, expr.col, typeArg ? `class ${expr.className}<${T.typeToString(typeArg)}>` : `class ${expr.className}`);
+        let ctorParams = this.lookupCtorParams(expr.className);
+        if (info.typeParam && typeArg) {
+            const paramName = info.typeParam;
+            const arg = typeArg;
+            ctorParams = ctorParams.map((p) => this.substituteTypeParam(p, paramName, arg));
+        }
         if (expr.args.length !== ctorParams.length) {
             this.diagnostics.error(`Expected ${ctorParams.length} constructor argument(s), got ${expr.args.length}`, expr.line, expr.col);
         }
@@ -1295,7 +1477,7 @@ export class Checker {
                 this.diagnostics.error(`Constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
             }
         });
-        return T.classType(expr.className);
+        return T.classType(expr.className, typeArg);
     }
     lookupCtorParams(className) {
         let current = className;
@@ -1399,6 +1581,11 @@ export class Checker {
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "string") {
+            // Marks this specific access as resolved against string's own
+            // built-ins, not some user member that merely shares the name —
+            // codegen's PascalCase -> camelCase renames rely on this, since they
+            // have no type information of their own to tell the two apart.
+            expr.isBuiltin = true;
             if (expr.property === "Length")
                 return { type: T.NUMBER, methodInfo: null };
             const method = STRING_METHODS[expr.property];
@@ -1408,6 +1595,7 @@ export class Checker {
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "array") {
+            expr.isBuiltin = true; // see the string branch above
             if (expr.property === "Length")
                 return { type: T.NUMBER, methodInfo: null };
             const method = this.arrayMethod(objectType.element, expr.property);
@@ -1439,6 +1627,12 @@ export class Checker {
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "class") {
+            // v1 has no generic inheritance (a generic class's base list can only
+            // name non-generic types), so a member found on a generic instance
+            // was always declared directly on that same class — substituting by
+            // its own type parameter, not some ancestor's, is always correct.
+            const paramName = objectType.typeArg ? this.genericTypeParams.get(objectType.name) : undefined;
+            const substitute = (type) => (paramName && objectType.typeArg ? this.substituteTypeParam(type, paramName, objectType.typeArg) : type);
             const field = this.lookupField(objectType.name, expr.property);
             if (field) {
                 this.checkAccessibility(field.info.visibility, field.owner, ctx, expr.property, expr.line, expr.col);
@@ -1448,12 +1642,13 @@ export class Checker {
                         this.diagnostics.error(`'${expr.property}' has no setter and can only be assigned within ${field.owner}'s constructor`, expr.line, expr.col);
                     }
                 }
-                return { type: field.info.type, methodInfo: null };
+                return { type: substitute(field.info.type), methodInfo: null };
             }
             const method = this.lookupMethod(objectType.name, expr.property);
             if (method) {
                 this.checkAccessibility(method.info.visibility, method.owner, ctx, expr.property, expr.line, expr.col);
-                return { type: method.info.returnType, methodInfo: method.info };
+                const info = paramName ? { ...method.info, params: method.info.params.map(substitute), returnType: substitute(method.info.returnType) } : method.info;
+                return { type: info.returnType, methodInfo: info };
             }
             this.diagnostics.error(`Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
@@ -1461,7 +1656,14 @@ export class Checker {
         if (objectType.kind === "interface") {
             const sig = this.collectInterfaceMethods(objectType.name).find((m) => m.name === expr.property);
             if (sig) {
-                return { type: sig.returnType, methodInfo: { params: sig.params, returnType: sig.returnType, visibility: "public", isVirtual: false, isOverride: false } };
+                // v1 has no generic interface inheritance either (same restriction
+                // as classes — see registerInterface), so a signature found here
+                // was always declared directly on this same interface.
+                const paramName = objectType.typeArg ? this.genericTypeParams.get(objectType.name) : undefined;
+                const substitute = (type) => (paramName && objectType.typeArg ? this.substituteTypeParam(type, paramName, objectType.typeArg) : type);
+                const params = sig.params.map(substitute);
+                const returnType = substitute(sig.returnType);
+                return { type: returnType, methodInfo: { params, returnType, visibility: "public", isVirtual: false, isOverride: false } };
             }
             this.diagnostics.error(`Interface '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };

package/dist/codegen.js

@@ -311,13 +311,24 @@ export class CodeGenerator {
         // Array.Push is non-mutating in KopScript, unlike JS's own (mutating,
         // length-returning) Array.prototype.push — so it can't just be a member
         // rename like Map/Filter/ForEach; it needs an entirely different call
-        // shape (a spread into a fresh array).
-        if (expr.callee.kind === "MemberExpr" && expr.callee.property === "Push" && expr.args.length === 1) {
+        // shape (a spread into a fresh array). Gated on `isBuiltin` (set by the
+        // checker only when the receiver is actually an array) so a user class
+        // with its own same-named `Push(x)` method — a natural name for any
+        // Stack<T>/List<T>-style container, now that generics exist — still
+        // compiles to a normal method call instead of this rewrite.
+        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])}]`;
         }
         return `${this.genExpr(expr.callee)}(${expr.args.map((a) => this.genExpr(a)).join(", ")})`;
     }
     genMember(expr) {
+        // PascalCase -> camelCase (and Length -> length) only applies to a
+        // genuine string/array built-in — see MemberExpr.isBuiltin's own
+        // comment for why this can't just be a name match. Anything else
+        // (including a user member that happens to share one of these names)
+        // passes through with its real, declared name untouched.
+        if (!expr.isBuiltin)
+            return `${this.genExpr(expr.object)}.${expr.property}`;
         const jsProperty = expr.property === "Length" ? "length" : MEMBER_METHOD_MAP[expr.property] ?? expr.property;
         return `${this.genExpr(expr.object)}.${jsProperty}`;
     }

package/dist/parser.js

@@ -200,9 +200,20 @@ export class Parser {
         this.consume(TokenKind.RParen, "Expected ')' after parameters");
         return params;
     }
+    // `<T>` right after a class/interface name — a single, unconstrained type
+    // parameter (v1 has no `Map<K, V>`, no `T : IFoo` constraints). Null if
+    // absent, the overwhelmingly common case.
+    parseOptionalTypeParam() {
+        if (!this.match(TokenKind.Lt))
+            return null;
+        const name = this.consume(TokenKind.Identifier, "Expected a type parameter name").lexeme;
+        this.consume(TokenKind.Gt, "Expected '>' after type parameter");
+        return name;
+    }
     parseClassDecl(isExported) {
         const start = this.advance(); // 'class'
         const name = this.consume(TokenKind.Identifier, "Expected class name").lexeme;
+        const typeParam = this.parseOptionalTypeParam();
         const baseList = [];
         if (this.match(TokenKind.Colon)) {
             do {
@@ -346,11 +357,12 @@ export class Parser {
             }
         }
         this.consume(TokenKind.RBrace, "Expected '}' after class body");
-        return { kind: "ClassDecl", isExported, name, baseList, fields, properties, constructor: ctor, methods, line: start.line, col: start.col };
+        return { kind: "ClassDecl", isExported, name, typeParam, baseList, fields, properties, constructor: ctor, methods, line: start.line, col: start.col };
     }
     parseInterfaceDecl(isExported) {
         const start = this.advance(); // 'interface'
         const name = this.consume(TokenKind.Identifier, "Expected interface name").lexeme;
+        const typeParam = this.parseOptionalTypeParam();
         const baseList = [];
         if (this.match(TokenKind.Colon)) {
             do {
@@ -376,7 +388,7 @@ export class Parser {
             });
         }
         this.consume(TokenKind.RBrace, "Expected '}' after interface body");
-        return { kind: "InterfaceDecl", isExported, name, baseList, methods, line: start.line, col: start.col };
+        return { kind: "InterfaceDecl", isExported, name, typeParam, baseList, methods, line: start.line, col: start.col };
     }
     parseEnumDecl(isExported) {
         const start = this.advance(); // 'enum'
@@ -621,7 +633,7 @@ export class Parser {
         }
         else if (this.check(TokenKind.Task)) {
             const taskTok = this.advance();
-            let resultType = { kind: "NamedType", name: "void", line: taskTok.line, col: taskTok.col };
+            let resultType = { kind: "NamedType", name: "void", typeArgs: null, line: taskTok.line, col: taskTok.col };
             if (this.match(TokenKind.Lt)) {
                 resultType = this.parseType();
                 this.consume(TokenKind.Gt, "Expected '>' after task result type");
@@ -637,7 +649,17 @@ export class Parser {
         }
         else {
             const nameToken = this.check(TokenKind.Void) ? this.advance() : this.consume(TokenKind.Identifier, "Expected type name");
-            type = { kind: "NamedType", name: nameToken.lexeme, line: nameToken.line, col: nameToken.col };
+            // `Box<number>` — a generic type reference. At most one type argument
+            // in v1 (matching ClassDecl/InterfaceDecl's single type parameter);
+            // whether `name` actually refers to a declared generic type is a
+            // semantic question the checker answers, not the parser.
+            let typeArgs = null;
+            if (this.check(TokenKind.Lt)) {
+                this.advance();
+                typeArgs = [this.parseType()];
+                this.consume(TokenKind.Gt, "Expected '>' after type argument");
+            }
+            type = { kind: "NamedType", name: nameToken.lexeme, typeArgs, line: nameToken.line, col: nameToken.col };
         }
         // `[]` and `?` are both postfix and can alternate in either order —
         // `string?[]` (array of nullable strings) and `string[]?` (nullable
@@ -815,6 +837,15 @@ export class Parser {
         if (this.check(TokenKind.New)) {
             this.advance();
             const className = this.consume(TokenKind.Identifier, "Expected class name after 'new'").lexeme;
+            // `new Box<number>(...)` — unambiguous here: `new <Identifier>` is
+            // always followed by `(`, generic type args or not, so seeing `<`
+            // instead can only mean a type argument list, never a comparison.
+            let typeArgs = null;
+            if (this.check(TokenKind.Lt)) {
+                this.advance();
+                typeArgs = [this.parseType()];
+                this.consume(TokenKind.Gt, "Expected '>' after type argument");
+            }
             this.consume(TokenKind.LParen, "Expected '(' after class name");
             const args = [];
             if (!this.check(TokenKind.RParen)) {
@@ -823,7 +854,7 @@ export class Parser {
                 } while (this.match(TokenKind.Comma));
             }
             this.consume(TokenKind.RParen, "Expected ')' after constructor arguments");
-            return { kind: "NewExpr", className, args, line: t.line, col: t.col };
+            return { kind: "NewExpr", className, typeArgs, args, line: t.line, col: t.col };
         }
         if (this.check(TokenKind.LBracket)) {
             this.advance();
@@ -861,36 +892,39 @@ export class Parser {
         this.diagnostics.error(`Unexpected token '${t.lexeme || t.kind}'`, t.line, t.col);
         throw new ParseError();
     }
-    // Lightweight lookahead (not a trial parse) distinguishing a lambda's
-    // parameter list from a parenthesized expression. A lambda parameter is
-    // always `Type name` (types are required, no inference in v1), so seeing
-    // two consecutive identifiers — or an empty `()` followed by `=>` — is
-    // unambiguous. This doesn't handle a lambda whose own first parameter is
-    // itself a function type (e.g. a higher-order lambda); that's a known v1
-    // gap in favor of keeping this check cheap.
+    // Distinguishes a lambda's parameter list from a parenthesized expression.
+    // A lambda parameter is always `Type name` (types are required, no
+    // inference in v1), so seeing a full type followed by an identifier — or
+    // an empty `()` followed by `=>` — is unambiguous. Uses a real speculative
+    // parse of the candidate type (same save-position/try/rollback shape as
+    // isDeclStart) rather than hand-rolled token lookahead, so it stays
+    // correct as parseType grows new postfix/prefix forms (`?`, `<T>`, ...)
+    // without needing a matching update here every time. This doesn't handle
+    // a lambda whose own first parameter is itself a function type (e.g. a
+    // higher-order lambda); that's a known v1 gap in favor of keeping this
+    // check simple.
     looksLikeLambda() {
-        let i = this.pos + 1; // just past '('
+        const i = this.pos + 1; // just past '('
         if (this.tokens[i]?.kind === TokenKind.RParen) {
             return this.tokens[i + 1]?.kind === TokenKind.Arrow;
         }
         const startKind = this.tokens[i]?.kind;
         if (startKind !== TokenKind.Identifier && startKind !== TokenKind.Void)
             return false;
-        i++;
-        // Mirrors parseType's postfix loop: `[]` and `?` can alternate in
-        // either order (`string?[]`, `string[]?`) after the base type name.
-        while (true) {
-            if (this.tokens[i]?.kind === TokenKind.LBracket && this.tokens[i + 1]?.kind === TokenKind.RBracket) {
-                i += 2;
-            }
-            else if (this.tokens[i]?.kind === TokenKind.Question) {
-                i += 1;
-            }
-            else {
-                break;
-            }
+        const savedPos = this.pos;
+        const savedDiagnosticsLength = this.diagnostics.diagnostics.length;
+        this.pos = i;
+        let result;
+        try {
+            this.parseType();
+            result = this.check(TokenKind.Identifier);
         }
-        return this.tokens[i]?.kind === TokenKind.Identifier;
+        catch {
+            result = false;
+        }
+        this.pos = savedPos;
+        this.diagnostics.diagnostics.length = savedDiagnosticsLength;
+        return result;
     }
     parseLambda() {
         const start = this.peek(); // '('

package/dist/types.js

@@ -6,11 +6,14 @@ export const UNKNOWN = { kind: "unknown" };
 export function arrayOf(element) {
     return { kind: "array", element };
 }
-export function classType(name) {
-    return { kind: "class", name };
+export function classType(name, typeArg) {
+    return typeArg ? { kind: "class", name, typeArg } : { kind: "class", name };
 }
-export function interfaceType(name) {
-    return { kind: "interface", name };
+export function interfaceType(name, typeArg) {
+    return typeArg ? { kind: "interface", name, typeArg } : { kind: "interface", name };
+}
+export function typeParamType(name) {
+    return { kind: "typeParam", name };
 }
 export function enumType(name) {
     return { kind: "enum", name };
@@ -37,10 +40,11 @@ export function typeToString(t) {
             return t.kind;
         case "array":
             return `${typeToString(t.element)}[]`;
-        case "class":
-        case "interface":
         case "enum":
             return t.name;
+        case "class":
+        case "interface":
+            return t.typeArg ? `${t.name}<${typeToString(t.typeArg)}>` : t.name;
         case "function":
             return `(${t.params.map(typeToString).join(", ")}) => ${typeToString(t.returnType)}`;
         case "task":
@@ -49,6 +53,8 @@ export function typeToString(t) {
             return `state<${typeToString(t.valueType)}>`;
         case "nullable":
             return `${typeToString(t.inner)}?`;
+        case "typeParam":
+            return t.name;
     }
 }
 const PRIMITIVE_NAMES = new Set(["number", "string", "bool", "void"]);
@@ -85,13 +91,33 @@ export function resolveTypeNode(node, namedTypes, onNamedType) {
         const inner = resolveTypeNode(node.inner, namedTypes, onNamedType);
         return inner ? nullableOf(inner) : null;
     }
+    // At most one type argument in v1 — resolve it once, up front; a
+    // primitive/enum/type-param name below never accepts one (arity error,
+    // caught as a plain resolution failure here — a class/interface's own
+    // required-vs-supplied arity mismatch is a separate check the caller
+    // makes, since only it knows which names are actually declared generic).
+    let typeArg = null;
+    if (node.typeArgs) {
+        typeArg = resolveTypeNode(node.typeArgs[0], namedTypes, onNamedType);
+        if (!typeArg)
+            return null;
+    }
     let resolved;
     if (PRIMITIVE_NAMES.has(node.name)) {
-        resolved = { kind: node.name };
+        resolved = typeArg ? null : { kind: node.name };
     }
     else {
         const kind = namedTypes.get(node.name);
-        resolved = kind === "class" ? classType(node.name) : kind === "interface" ? interfaceType(node.name) : kind === "enum" ? enumType(node.name) : null;
+        if (kind === "class")
+            resolved = classType(node.name, typeArg ?? undefined);
+        else if (kind === "interface")
+            resolved = interfaceType(node.name, typeArg ?? undefined);
+        else if (kind === "enum")
+            resolved = typeArg ? null : enumType(node.name);
+        else if (kind === "typeParam")
+            resolved = typeArg ? null : typeParamType(node.name);
+        else
+            resolved = null;
     }
     if (resolved)
         onNamedType?.(node, resolved);
@@ -116,8 +142,25 @@ export function typesEqual(a, b) {
     if (a.kind === "nullable" && b.kind === "nullable") {
         return typesEqual(a.inner, b.inner);
     }
-    if ((a.kind === "class" || a.kind === "interface" || a.kind === "enum") && "name" in b) {
+    if (a.kind === "typeParam" && b.kind === "typeParam") {
         return a.name === b.name;
     }
+    // Invariant generics: Box<number> and Box<string> are unrelated types,
+    // and so are Box<number> and bare (non-generic-reference) Box — the
+    // latter only arises from an arity error already diagnosed elsewhere, so
+    // treating it as unequal here (rather than papering over it) is right.
+    if ((a.kind === "class" || a.kind === "interface" || a.kind === "enum") && "name" in b) {
+        const other = b;
+        if (a.name !== other.name)
+            return false;
+        if ("typeArg" in a || "typeArg" in other) {
+            const aArg = a.typeArg;
+            const bArg = other.typeArg;
+            if (!aArg || !bArg)
+                return false;
+            return typesEqual(aArg, bArg);
+        }
+        return true;
+    }
     return true;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kopscript",
-  "version": "0.3.0",
-  "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript",
+  "version": "0.4.0",
+  "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",
   "author": "Joe Koppin <koppinjo@gmail.com>",