Update doc

Batiste Bieler · Batiste Bieler · commit 73871ce35498 · 2026-03-05T09:08:34.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-03-05
+
+This release continues to strengthen the type system and developer experience with immutability
+patterns, improved type narrowing, and better error diagnostics.
+
+### Added
+
+**Type system**
+- `readonly` modifier for object properties and arrays: prevent accidental mutations and catch
+  errors at compile time. Syntax: `readonly name: string`, `readonly string[]` (#84).
+- `as const` assertions: freeze inferred types to their literal equivalents. Useful for creating
+  immutable configuration objects and type-safe enums (#85).
+- Type narrowing on object sub-elements: `if obj?.property` now correctly narrows the type of
+  nested properties within the conditional block.
+- "Object is possibly undefined" warnings: improved diagnostics when accessing properties on
+  potentially nullish objects (#86).
+
+**Editor & diagnostics**
+- Auto-completion improvements: better handling of optional chaining when suggesting property
+  and method names.
+- Improved error messages: clearer explanations of type mismatches and compilation failures.
+- Enhanced arity checking: better error reporting when function calls have incorrect argument
+  counts with suggestions for fixes (#87).
+
+**Formatting & code quality**
+- Whitespace enforcement: stricter parsing limits to maximum 2 consecutive spaces to encourage
+  consistent code style and prevent accidental formatting issues.
+
+### Changed
+
+- Type narrowing logic refined to handle nested property access patterns more accurately.
+- Error message formatting improved for readability.
+
+### Fixed
+
+- Auto-completion with optional chaining operator (`?.`) now suggests correct members.
+- Edge cases in type narrowing on sub-elements.
+
+---
+
 ## [1.2.0] - 2026-02-25
 
 This release focuses heavily on making the language more solid: the inference engine
diff --git a/docs/MODERN_FEATURES.md b/docs/MODERN_FEATURES.md
@@ -311,6 +311,96 @@ The compiler registers dynamic import paths in the module's dependency list, so
 - Conditional features (load a debug panel only in development)
 - Plugin systems
 
+## Immutability
+
+Blop provides two powerful tools to enforce immutability and prevent accidental mutations: `readonly` and `as const`.
+
+### The readonly Modifier
+
+The `readonly` modifier marks individual properties or arrays as immutable. Any attempt to modify a readonly field results in a compile-time error.
+
+```typescript
+type User = {
+  readonly id: number,
+  readonly name: string,
+  email: string      // mutable
+}
+
+user: User = { id: 1, name: 'Alice', email: 'alice@example.com' }
+
+// ❌ Error: cannot mutate readonly property
+user.id = 2
+user.name = 'Bob'
+
+// ✅ OK: email is not readonly
+user.email = 'alice.new@example.com'
+```
+
+Readonly also works with arrays:
+
+```typescript
+forbiddenIds: readonly number[] = [1, 2, 3]
+
+// ❌ Error: cannot mutate readonly array
+forbiddenIds.push(4)
+forbiddenIds[0] = 10
+
+// ✅ OK: reading values
+count = forbiddenIds.length
+```
+
+### The as const Assertion
+
+`as const` is a powerful assertion that freezes an entire object or array, converting all types to their literal equivalents and marking everything as readonly:
+
+```typescript
+// Without as const: { status: string }
+settings1 = { status: 'active' }
+
+// With as const: { readonly status: 'active' }
+settings2 = { status: 'active' } as const
+```
+
+This is particularly useful for creating type-safe enums and configuration constants:
+
+```typescript
+// Type-safe enum pattern
+HttpStatus = {
+  OK: 200,
+  NotFound: 404,
+  ServerError: 500
+} as const
+// Type: { readonly OK: 200, readonly NotFound: 404, readonly ServerError: 500 }
+
+// Now the type system knows exact values, enabling better type checking
+code: HttpStatus.OK = HttpStatus.OK    // ✅ OK
+code2: HttpStatus.NotFound = HttpStatus.OK  // ❌ Error: 200 is not assignable to 404
+```
+
+Array literals with `as const`:
+
+```typescript
+AllowedRoles = ['admin', 'user', 'guest'] as const
+// Type: readonly ['admin', 'user', 'guest']
+
+role1: AllowedRoles = 'admin'    // ✅ OK
+role2: AllowedRoles = 'owner'    // ❌ Error: 'owner' is not in the literal type
+```
+
+### Key Differences
+
+| Feature | `readonly` | `as const` |
+|---------|-----------|-----------|
+| Scope | Individual properties | Entire object/array |
+| Type change | Keeps general type | Converts to literal types |
+| Use case | Data structures with some mutable fields | Immutable constants and enums |
+| Syntax | `readonly name: string` | `obj as const` |
+
+### Use Cases
+
+- **readonly**: Data transfer objects with mostly immutable fields, API configurations, frozen lookups
+- **as const**: Feature flags, HTTP status codes, permission levels, immutable configuration tables
+
 ## Testing
 
 Tests for modern features are in [src/tests/modern-features.test.blop](../src/tests/modern-features.test.blop).
diff --git a/docs/SYNTAX_REFERENCE.md b/docs/SYNTAX_REFERENCE.md
@@ -13,6 +13,7 @@ A practical reference for writing Blop code. Each section explains the syntax, s
 - [Objects and Arrays](#objects-and-arrays)
 - [Classes](#classes)
 - [Type Aliases](#type-aliases)
+- [Type Modifiers](#type-modifiers)
 - [try / catch / throw](#try--catch--throw)
 - [Compound Assignment](#compound-assignment)
 - [Virtual DOM](#virtual-dom)
@@ -291,6 +292,51 @@ def greet(u: User): string {
 }
 ```
 
+### Type Modifiers
+
+#### readonly
+
+The `readonly` modifier prevents modification of object properties and arrays. Attempting to modify a readonly field results in a compile-time error:
+
+```typescript
+// Readonly properties in objects
+type Config = {
+  readonly apiUrl: string,
+  readonly timeout: number,
+  retries: number
+}
+
+// Readonly arrays
+type StringList = readonly string[]
+
+// Using readonly in variables
+config: Config = { readonly apiUrl: 'https://api.example.com', timeout: 5000, retries: 3 }
+config.apiUrl = 'https://new-api.example.com'  // ❌ Compile error: cannot mutate readonly property
+config.retries = 4                             // ✅ OK: retries is mutable
+```
+
+#### as const
+
+The `as const` assertion freezes an object or array to use literal types instead of general types. This is useful for creating immutable configuration objects and type-safe enums:
+
+```typescript
+// Without as const: inferred as { name: string, level: number }
+settings = { name: 'default', level: 1 }
+
+// With as const: inferred as { readonly name: 'default', readonly level: 1 }
+immutableSettings = { name: 'default', level: 1 } as const
+
+// as const with arrays: preserves specific value types
+directions = ['north', 'south', 'east', 'west'] as const
+// Type: readonly ['north', 'south', 'east', 'west']
+
+// Type-safe enums
+Status = { Active: 'active', Inactive: 'inactive' } as const
+// Type: { readonly Active: 'active', readonly Inactive: 'inactive' }
+```
+
+When you use `as const`, all nested types become readonly and use literal types, making them safer for constants and immutable data structures.
+
 ---
 
 ## try / catch / throw
diff --git a/docs/TYPESCRIPT_GAP_ANALYSIS.md b/docs/TYPESCRIPT_GAP_ANALYSIS.md
@@ -28,6 +28,8 @@ This document tracks which TypeScript type-system features are present in Blop a
 | Dead code detection (unreachable code after `return` / `throw`) | `statements.js` — warns on code after an unconditional early exit |
 | **Tuple types (`[string, number]`)** | `TupleType` — see design notes below |
 | **`as` type assertion** | Grammar reuses the `as` keyword; inference stamps asserted type; backend erases the annotation |
+| **`as const` / const assertions** | `{ x: 1 } as const` — freeze inferred types to literal equivalents; recursively convert to `LiteralType` |
+| **`readonly` modifier** | `readonly name: string`, `readonly T[]` — `readonly` flag on `ObjectType` properties and `ArrayType`; errors on assignment |
 | **User-defined type predicates (`x is T`)** | `PredicateType` — see design notes below |
 | **`keyof` operator** | `KeyofType` — see design notes below |
 | **Class member type annotations** | `classMembers.test.js` — member type annotations, method signatures, and `this` inference all work |
@@ -50,45 +52,44 @@ These are self-contained, add immediate practical value, and do not require majo
 
 | # | Feature | TS example | Blocked by | Notes |
 |---|---|---|---|---|
-| 1 | **`as const` / const assertions** | `{ x: 1 } as const` | — | Freeze all inferred types to their literal equivalents. Reuse `as` grammar; add a `constAssertion` flag. Recursively convert `number` → `LiteralType(n)`, `string` → `LiteralType(s)`, turn object values into readonly literals. |
-| 2 | **`readonly` modifier** | `readonly name: string`, `readonly T[]` | — | Add a `readonly` flag in `ObjectType` properties and `ArrayType`. Emit a type error on assignment. Grammar: add `readonly` as an optional prefix on property annotations and array type syntax. No new `Type` subclass needed. |
-| 3 | **`satisfies` operator** | `expr satisfies T` | `as` infrastructure | Like `as` but with a compatibility check: error if the expression type is not assignable to `T`. Reuse `parseTypeExpression` + `isCompatibleWith`; keep the original inferred type (not the asserted one) for downstream inference. A strict complement to `as`. |
-| 4 | **Exhaustiveness checking** | `switch (x) { … }` + `never` narrowing | Type narrowing | After all branches of an `if/else` or `switch` have been handled, the remaining type should reduce to `never`. Emit a warning if a `never`-typed value is used (e.g. returned). Extend the checking phase's narrowing logic in `statements.js`. |
+| 1 | **`satisfies` operator** | `expr satisfies T` | `as` infrastructure | Like `as` but with a compatibility check: error if the expression type is not assignable to `T`. Reuse `parseTypeExpression` + `isCompatibleWith`; keep the original inferred type (not the asserted one) for downstream inference. A strict complement to `as`. |
+| 2 | **Exhaustiveness checking** | `switch (x) { … }` + `never` narrowing | Type narrowing | After all branches of an `if/else` or `switch` have been handled, the remaining type should reduce to `never`. Emit a warning if a `never`-typed value is used (e.g. returned). Extend the checking phase's narrowing logic in `statements.js`. |
 
 ### Tier 2 — Medium complexity (unlock utility types)
 
 These require new `Type` subclasses but have well-understood semantics.
 
 | # | Feature | TS example | Blocked by | Notes |
 |---|---|---|---|---|
-| 6 | **Mapped types** | `{ [K in keyof T]: T[K] }` | `keyof` ✓ | New `MappedType` class with `keyParam`, `sourceType`, `valueExpr`. Resolution: expand `keyof sourceType`, bind `K` to each key, evaluate `valueExpr`. Unlocks `Partial<T>`, `Required<T>`, `Pick<T,K>`, `Omit<T,K>` as standard library aliases. |
-| 7 | **Conditional types** | `T extends U ? X : Y` | New `ConditionalType` | New `ConditionalType` class with `checkType`, `extendsType`, `trueType`, `falseType`. Resolution: check if `checkType` is assignable to `extendsType`; pick branch. Enables `ReturnType<F>`, `Parameters<F>`, `NonNullable<T>`. |
-| 8 | **`infer` keyword** | `T extends Array<infer E>` | Conditional types | Binding mechanism inside the `extendsType` of a conditional. The `infer` variable is in scope only in the true branch. |
-| 9 | **`Partial<T>`, `Required<T>`, `Pick<T,K>`, `Omit<T,K>`** | — | Mapped types | Once mapped types land, these become simple type alias definitions in `stdlib.js`. |
-| 10 | **`ReturnType<F>`, `Parameters<F>`** | — | Conditional + `infer` | `ReturnType<F>` = `F extends (...args: any[]) => infer R ? R : never`. |
-| 11 | **Function overloads** | Multiple call signatures | — | `FunctionType[]` per symbol. At call sites: find the first compatible overload. Grammar: a block of signature declarations before the implementation body. |
-| 12 | **Template literal types** | `` `prefix-${string}` `` | New `TemplateLiteralType` | `TemplateLiteralType` with `parts: Array<string \| Type>`. Evaluates against string literal types; widens to `string` otherwise. |
+| 3 | **Mapped types** | `{ [K in keyof T]: T[K] }` | `keyof` ✓ | New `MappedType` class with `keyParam`, `sourceType`, `valueExpr`. Resolution: expand `keyof sourceType`, bind `K` to each key, evaluate `valueExpr`. Unlocks `Partial<T>`, `Required<T>`, `Pick<T,K>`, `Omit<T,K>` as standard library aliases. |
+| 4 | **Conditional types** | `T extends U ? X : Y` | New `ConditionalType` | New `ConditionalType` class with `checkType`, `extendsType`, `trueType`, `falseType`. Resolution: check if `checkType` is assignable to `extendsType`; pick branch. Enables `ReturnType<F>`, `Parameters<F>`, `NonNullable<T>`. |
+| 5 | **`infer` keyword** | `T extends Array<infer E>` | Conditional types | Binding mechanism inside the `extendsType` of a conditional. The `infer` variable is in scope only in the true branch. |
+| 6 | **`Partial<T>`, `Required<T>`, `Pick<T,K>`, `Omit<T,K>`** | — | Mapped types | Once mapped types land, these become simple type alias definitions in `stdlib.js`. |
+| 7 | **`ReturnType<F>`, `Parameters<F>`** | — | Conditional + `infer` | `ReturnType<F>` = `F extends (...args: any[]) => infer R ? R : never`. |
+| 8 | **Function overloads** | Multiple call signatures | — | `FunctionType[]` per symbol. At call sites: find the first compatible overload. Grammar: a block of signature declarations before the implementation body. |
+| 9 | **Template literal types** | `` `prefix-${string}` `` | New `TemplateLiteralType` | `TemplateLiteralType` with `parts: Array<string \| Type>`. Evaluates against string literal types; widens to `string` otherwise. |
 
 ### Tier 3 — Advanced / lower immediate impact
 
+| # | Feature | TS example | Notes |
 | # | Feature | TS example | Notes |
 |---|---|---|---|
-| 13 | **`typeof x` in annotation position** | `type T = typeof someVar` | Type query — resolves to the inferred type of a variable. Requires look-up in the scope snapshot at declaration site. |
-| 14 | **`implements` interface checking** | `class Foo implements IFoo` | Class member annotations are already typed; `implements` would cross-check the class shape against a declared object type at the class-definition node. Straightforward extension of the existing excess-properties check. |
-| 15 | **Generic constraints** | `K extends keyof T` | Grammar for `extends` on type parameters; enforce in `substituteTypeParams`. `keyof` exists but cannot yet appear as a constraint. |
-| 16 | **Assertion functions** | `asserts cond` | Grammar + narrowing — analog to `PredicateType`; requires an `AssertionType` class and narrowing in the post-call scope. |
-| 17 | **Exhaustiveness in discriminated unions** | `switch (tag) { case 'a': … }` | Extension of Tier 1 #5; matches on literal types to peel the union case-by-case. |
-| 18 | **Declaration / interface merging** | Same-name type aliases | Symbol table change: collect all declarations of a name and merge their shapes. |
-| 19 | **Variance annotations** | `in`/`out` on generics | New flag on `GenericType`; enforced during `isCompatibleWith` on generic arguments. |
+| 10 | **`typeof x` in annotation position** | `type T = typeof someVar` | Type query — resolves to the inferred type of a variable. Requires look-up in the scope snapshot at declaration site. |
+| 11 | **`implements` interface checking** | `class Foo implements IFoo` | Class member annotations are already typed; `implements` would cross-check the class shape against a declared object type at the class-definition node. Straightforward extension of the existing excess-properties check. |
+| 12 | **Generic constraints** | `K extends keyof T` | Grammar for `extends` on type parameters; enforce in `substituteTypeParams`. `keyof` exists but cannot yet appear as a constraint. |
+| 13 | **Assertion functions** | `asserts cond` | Grammar + narrowing — analog to `PredicateType`; requires an `AssertionType` class and narrowing in the post-call scope. |
+| 14 | **Exhaustiveness in discriminated unions** | `switch (tag) { case 'a': … }` | Extension of Tier 1 #2; matches on literal types to peel the union case-by-case. |
+| 15 | **Declaration / interface merging** | Same-name type aliases | Symbol table change: collect all declarations of a name and merge their shapes. |
+| 16 | **Variance annotations** | `in`/`out` on generics | New flag on `GenericType`; enforced during `isCompatibleWith` on generic arguments. |
 
 ---
 
 ## What Would Move the Needle Most
 
 If the goal is maximum practical value for Blop programs written today, the suggested order of attack is:
 
-1. **`as const`** — unlocks literal-type patterns everywhere; touches only the `as` infrastructure already in place.
-2. **`readonly`** — adds an immutability safety net; property flag, no new type class.
+1. ✅ **`as const`** — unlocks literal-type patterns everywhere; touches only the `as` infrastructure already in place. **DONE as of v1.3.0**.
+2. ✅ **`readonly`** — adds an immutability safety net; property flag, no new type class. **DONE as of v1.3.0**.
 3. **`satisfies`** — adds the strict complement to `as`; reuses all type-check infrastructure.
 4. **Exhaustiveness checking** — big DX win for discriminated-union patterns; extends existing dead-code logic.
 5. **Mapped types** — medium effort, high reward: immediately unlocks `Partial`, `Pick`, `Omit`, `Required`.
