Add mapped types

Author: Batiste Bieler

src/constants.js

@@ -205,6 +205,19 @@ const BUILTIN_TYPES = new Set([
 
   // Legacy/alias types
   'int',
+
+  // Built-in utility generic types (TypeScript-compatible)
+  'Record',
+  'Partial',
+  'Required',
+  'Readonly',
+  'Pick',
+  'Omit',
+  'Exclude',
+  'Extract',
+  'NonNullable',
+  'ReturnType',
+  'Parameters',
 ]);
 
 /**

src/grammar.js

@@ -107,12 +107,14 @@ const grammar = {
     ['readonly:readonly', 'type_primary:inner'],
     ['keyof', 'type_primary:subject', 'array_suffix?'],
     ['tuple_type:tuple', 'array_suffix?'],
+    ['mapped_type:mapped'],
     ['object_type', 'array_suffix?'],
     ['str:literal', 'array_suffix?'],
     ['number:literal', 'array_suffix?'],
     ['type_name:name', '<', 'type_arg_list:type_args', '>', 'array_suffix?'],
     ['type_name:name', '<', 'type_arg_list:type_args', '>'],
     ['type_name:name', '.', 'name:member', 'array_suffix?'],
+    ['type_name:name', '[', 'name:index_key', ']', 'array_suffix?'],
     ['type_name:name', '[', 'str:member_key', ']', 'array_suffix?'],
     ['type_name:name', 'array_suffix?'],
   ],
@@ -139,6 +141,10 @@ const grammar = {
     ['{', 'single_space_or_newline', 'object_type_properties:properties', 'single_space_or_newline', '}'],
     ['{', '}'],
   ],
+  'mapped_type': [
+    ['{', 'single_space_or_newline', 'readonly:readonly', 'w', '[', 'name:key_param', 'w', 'in', 'type_expression:source', ']', 'question?:optional', 'colon', 'w?', 'type_expression:value', 'single_space_or_newline', '}'],
+    ['{', 'single_space_or_newline', '[', 'name:key_param', 'w', 'in', 'type_expression:source', ']', 'question?:optional', 'colon', 'w?', 'type_expression:value', 'single_space_or_newline', '}'],
+  ],
   'object_type_properties': [
     ['object_type_property', ',', 'single_space_or_newline', 'object_type_properties'],
     ['object_type_property', ','],

src/inference/Type.js

@@ -354,7 +354,7 @@ export class ObjectType extends Type {
     }
 
     // Resolve aliases and type member access
-    if (target instanceof TypeAlias || target instanceof TypeMemberAccess || target instanceof KeyofType) {
+    if (target instanceof TypeAlias || target instanceof TypeMemberAccess || target instanceof KeyofType || target instanceof MappedType || target instanceof TypeIndexAccess) {
       const resolved = aliases.resolve(target);
       // Avoid infinite recursion if alias can't be resolved
       if (resolved === target) return false;
@@ -1023,6 +1023,85 @@ export class TypeMemberAccess extends Type {
   }
 }
 
+/**
+ * Mapped type: { [K in source]: valueType }
+ * Represents a mapped object type that iterates over keys of a source type.
+ * When resolved, expands to an ObjectType with one property per key.
+ */
+export class MappedType extends Type {
+  /**
+   * @param {string} keyParam - The name of the key parameter (e.g. 'K')
+   * @param {Type} sourceType - The source type whose keys to iterate (e.g. KeyofType)
+   * @param {Type} valueType - The value type expression (may reference keyParam)
+   * @param {boolean} optional - Whether properties should be optional
+   * @param {boolean} readonly - Whether properties should be readonly
+   */
+  constructor(keyParam, sourceType, valueType, optional = false, readonly = false) {
+    super();
+    this.kind = 'mapped';
+    this.keyParam = keyParam;
+    this.sourceType = sourceType;
+    this.valueType = valueType;
+    this.optional = optional;
+    this.readonly = readonly;
+  }
+
+  toString() {
+    const ro = this.readonly ? 'readonly ' : '';
+    const opt = this.optional ? '?' : '';
+    return `{ ${ro}[${this.keyParam} in ${this.sourceType}]${opt}: ${this.valueType} }`;
+  }
+
+  equals(other) {
+    return other instanceof MappedType
+      && this.keyParam === other.keyParam
+      && this.sourceType.equals(other.sourceType)
+      && this.valueType.equals(other.valueType)
+      && this.optional === other.optional;
+  }
+
+  isCompatibleWith(target, aliases) {
+    const resolved = aliases.resolve(this);
+    if (resolved !== this) return resolved.isCompatibleWith(target, aliases);
+    if (isAnyType(target)) return true;
+    return this.equals(target);
+  }
+}
+
+/**
+ * Indexed type access: T[K] where K is a type variable or literal.
+ * Used in mapped type value expressions like T[K].
+ */
+export class TypeIndexAccess extends Type {
+  /**
+   * @param {Type} baseType - The type being indexed (e.g. TypeAlias('T'))
+   * @param {Type} keyType - The key type (e.g. TypeAlias('K') or LiteralType)
+   */
+  constructor(baseType, keyType) {
+    super();
+    this.kind = 'index_access';
+    this.baseType = baseType;
+    this.keyType = keyType;
+  }
+
+  toString() {
+    return `${this.baseType}[${this.keyType}]`;
+  }
+
+  equals(other) {
+    return other instanceof TypeIndexAccess
+      && this.baseType.equals(other.baseType)
+      && this.keyType.equals(other.keyType);
+  }
+
+  isCompatibleWith(target, aliases) {
+    const resolved = aliases.resolve(this);
+    if (resolved !== this) return resolved.isCompatibleWith(target, aliases);
+    if (isAnyType(target)) return true;
+    return this.equals(target);
+  }
+}
+
 /**
  * Type alias reference (not resolved yet)
  */
@@ -1157,6 +1236,59 @@ export class TypeAliasMap {
     return StringType;
   }
 
+  /**
+   * Resolve a TypeIndexAccess T[K] to the concrete property type.
+   * If K is a string literal and T is an ObjectType, looks up the property.
+   * @param {TypeIndexAccess} type
+   * @returns {Type}
+   */
+  resolveIndexAccess(type) {
+    const resolvedBase = this.resolve(type.baseType);
+    const resolvedKey = this.resolve(type.keyType);
+    if (resolvedBase instanceof ObjectType && resolvedKey instanceof LiteralType) {
+      const prop = resolvedBase.properties.get(resolvedKey.value);
+      if (prop) return prop.type;
+    }
+    if (resolvedBase instanceof PrimitiveType && resolvedBase.name === 'any') return AnyType;
+    return AnyType;
+  }
+
+  /**
+   * Resolve a MappedType by expanding its key set and building an ObjectType.
+   * @param {MappedType} type
+   * @returns {Type}
+   */
+  resolveMappedType(type) {
+    const resolvedSource = this.resolve(type.sourceType);
+
+    // Collect the concrete key literals
+    let keyLiterals;
+    if (resolvedSource instanceof UnionType) {
+      keyLiterals = resolvedSource.types.filter(t => t instanceof LiteralType && t.baseType === StringType);
+    } else if (resolvedSource instanceof LiteralType && resolvedSource.baseType === StringType) {
+      keyLiterals = [resolvedSource];
+    } else if (resolvedSource instanceof PrimitiveType && resolvedSource.name === 'string') {
+      // Open key set — produce a RecordType
+      const subs = new Map([[type.keyParam, StringType]]);
+      const resolvedValue = this.resolve(substituteTypeParams(type.valueType, subs));
+      return new RecordType(StringType, resolvedValue);
+    } else {
+      // Cannot determine keys — fallback
+      return AnyType;
+    }
+
+    if (keyLiterals.length === 0) return new ObjectType(new Map());
+
+    const newProps = new Map();
+    for (const keyLiteral of keyLiterals) {
+      const subs = new Map([[type.keyParam, keyLiteral]]);
+      const substituted = substituteTypeParams(type.valueType, subs);
+      const resolvedValue = this.resolve(substituted);
+      newProps.set(String(keyLiteral.value), { type: resolvedValue, optional: type.optional, readonly: type.readonly });
+    }
+    return new ObjectType(newProps);
+  }
+
   /**
    * Resolve a type alias (recursive with cycle detection)
    * @param {Type} type
@@ -1169,6 +1301,12 @@ export class TypeAliasMap {
     if (type instanceof KeyofType) {
       return this.resolveKeyof(type);
     }
+    if (type instanceof TypeIndexAccess) {
+      return this.resolveIndexAccess(type);
+    }
+    if (type instanceof MappedType) {
+      return this.resolveMappedType(type);
+    }
     if (!(type instanceof TypeAlias)) {
       return type;
     }
@@ -1307,6 +1445,26 @@ export function substituteTypeParams(type, substitutions) {
     return new KeyofType(substituteTypeParams(type.subjectType, substitutions));
   }
 
+  if (type instanceof MappedType) {
+    // Substitute in sourceType and valueType, but NOT in keyParam (it's a bound variable)
+    const filteredSubs = new Map(substitutions);
+    filteredSubs.delete(type.keyParam); // keyParam is locally bound — don't substitute it
+    return new MappedType(
+      type.keyParam,
+      substituteTypeParams(type.sourceType, substitutions),
+      substituteTypeParams(type.valueType, filteredSubs),
+      type.optional,
+      type.readonly
+    );
+  }
+
+  if (type instanceof TypeIndexAccess) {
+    return new TypeIndexAccess(
+      substituteTypeParams(type.baseType, substitutions),
+      substituteTypeParams(type.keyType, substitutions)
+    );
+  }
+
   // Primitives and literals don't need substitution
   return type;
 }

src/inference/handlers/expressions.js

@@ -69,10 +69,10 @@ function handleExpObjAccess(node, parent, getState) {
 function handleSimpleVariable(name, parent, definition, getState) {
   const { pushInference, typeAliases, pushWarning, inferencePhase } = getState();
 
-  // Exhaustiveness check: if a variable has been narrowed to `never` by the type
-  // guard system (i.e. all union cases have been handled via early-return guards),
-  // reading it is dead code — all possible values have already been accounted for.
-  if (inferencePhase === 'checking' && definition?.narrowed && definition.type === NeverType) {
+  // Exhaustiveness check: if a variable has been marked as exhausted by applyPostIfGuard
+  // (i.e. all union cases have been handled via prior early-return guards), reading it is
+  // dead code — all possible values have already been accounted for.
+  if (inferencePhase === 'checking' && definition?.__exhausted) {
     pushWarning(name, `'${name.value}' has been narrowed to 'never' — this code is unreachable: all union cases are already handled above`);
   }
 

src/inference/typeGuards.js

@@ -553,6 +553,8 @@ function applyElseBranchGuard(scope, typeGuard, lookupVariable, typeAliases) {
 /**
  * Apply the correct scope effect to the outer scope after an early-return if guard.
  * Same semantics as applyElseBranchGuard: code past the if block is the "false" path.
+ * When the result of the exclusion is `never`, the variable is marked as `__exhausted`
+ * so that the exhaustiveness checker can warn on subsequent uses.
  * @param {Object} typeAliases - Required when typeGuard.property is set
  */
 function applyPostIfGuard(scope, typeGuard, lookupVariable, typeAliases) {
@@ -577,6 +579,11 @@ function applyPostIfGuard(scope, typeGuard, lookupVariable, typeAliases) {
   } else {
     applyExclusion(scope, typeGuard.variable, typeGuard.checkType, lookupVariable);
   }
+  // Mark as exhausted if exclusion reduced the type to `never` — enables exhaustiveness warnings
+  const afterDef = scope[typeGuard.variable];
+  if (afterDef && afterDef.type?.kind === 'primitive' && afterDef.type?.name === 'never') {
+    afterDef.__exhausted = true;
+  }
 }
 
 /**

src/inference/typeParser.js

@@ -6,7 +6,7 @@ import {
   Type, Types, TypeAlias, TypeMemberAccess, KeyofType, UnionType, IntersectionType, ArrayType, ObjectType,
   TupleType, GenericType, LiteralType, PrimitiveType, PredicateType,
   StringType, NumberType, BooleanType, NullType, UndefinedType,
-  AnyFunctionType, FunctionType
+  AnyFunctionType, FunctionType, MappedType, TypeIndexAccess
 } from './Type.js';
 
 /**
@@ -129,6 +129,11 @@ export function parseTypePrimary(typePrimaryNode) {
     return baseType;
   }
 
+  // Check for mapped type: { [K in source]: value }
+  if (typePrimaryNode.named.mapped) {
+    return parseMappedType(typePrimaryNode.named.mapped);
+  }
+
   // Check for readonly type: readonly T[]
   if (typePrimaryNode.named.readonly) {
     const innerType = parseTypePrimary(typePrimaryNode.named.inner);
@@ -156,7 +161,7 @@ export function parseTypePrimary(typePrimaryNode) {
     const value = parseFloat(typePrimaryNode.named.literal.value);
     baseType = Types.literal(value, NumberType);
   } else {
-    const { name, type_args, member, member_key } = typePrimaryNode.named;
+    const { name, type_args, member, member_key, index_key } = typePrimaryNode.named;
     if (name) {
       // name is a type_name node, get its first child
       const typeToken = name.children ? name.children[0] : name;
@@ -169,6 +174,11 @@ export function parseTypePrimary(typePrimaryNode) {
           : member_key.value.slice(1, -1); // strip surrounding quotes
         baseType = new TypeMemberAccess(new TypeAlias(typeName), key);
       } else
+      // Check for index type access: T[K] where K is a type variable name
+      if (index_key) {
+        const keyName = index_key.value ?? (index_key.children?.[0]?.value);
+        baseType = new TypeIndexAccess(new TypeAlias(typeName), new TypeAlias(keyName));
+      } else
       // Check if it's a generic type instantiation: Type<Args>
       if (type_args) {
         const typeArgs = parseTypeArguments(type_args);
@@ -208,6 +218,21 @@ function parseTupleTypeElements(node) {
   return types;
 }
 
+/**
+ * Parse a mapped_type AST node into a MappedType
+ * Grammar: { [K in source]: value }  or  { readonly [K in source]?: value }
+ * @param {Object} mappedTypeNode - The mapped_type AST node
+ * @returns {MappedType}
+ */
+function parseMappedType(mappedTypeNode) {
+  if (!mappedTypeNode || !mappedTypeNode.named) return Types.any;
+  const { key_param, source, value, optional, readonly } = mappedTypeNode.named;
+  const keyParam = key_param?.value ?? 'K';
+  const sourceType = parseTypeExpression(source);
+  const valueType = parseTypeExpression(value);
+  return new MappedType(keyParam, sourceType, valueType, !!optional, !!readonly);
+}
+
 /**
  * Parse an array_suffix node to handle one or more [] pairs
  * Multi-dimensional arrays recursively wrap the type