Why does TypeScript allow assignment of a subtype to an object property?

Consider this example:

type Base = {
    a: number,
    b: number
}

type SubTest = Base & {
    c: number
}

function run(arg: { prop: Base }) {
    arg.prop = {
        a: 1,
        b: 2
    };
}

const prop: SubTest = {
    a: 1,
    b: 2,
    c: 3
};

const originalObject = { prop };

run(originalObject);

console.log(originalObject.prop.c.toFixed(2));

TypeScript seems perfectly okay with this, but the resulting JS produces the obvious error:

> originalObject.prop.c is undefined

.tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "strict": true,
    "sourceMap": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "noImplicitThis": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./resources/js/*"]
    },
    "types": [
        "vite/client"
    ],
    "skipLibCheck": true
  },
  ...
}

Since, SubTest extends Base, which means that SubTest is a sub-type of Base, you can pass any SubTest as Base. You can interpret that to how OOP works, you can pass a child class to a method that expects the parent class. The issue here is that for Typescript everything is fine since you expect exactly a Base and as mentioned before, SubTest obeys this condition.

The reason why such an assignment is possible is due to Typescript's type system, which is known as structural type system, that only checks if the needed shape of the type is reached and doesn't check for the additional fields. In simple words compared to Java, Typescript checks only for the existence of the required fields, while Java checks for the exact identity.

Basically, you could define another type that is independent of Base, but has its all fields, and run wouldn't complain about it:

type NotBase = {
   a: number;
   b: number;
}

const notBase: NotBase = {a: 1, b: 2};

run({ prop: notBase }); // no error

If we refer to official docs we can see exactly the same situation happening:

interface Point {
  x: number;
  y: number;
}
 
function logPoint(p: Point) {
  console.log(`${p.x}, ${p.y}`);
}

const point = { x: 12, y: 26 };
logPoint(point); // no error

> The point variable is never declared to be a Point type. However, TypeScript compares the shape of point to the shape of Point in the type-check. They have the same shape, so the code passes. The shape-matching only requires a subset of the object’s fields to match.

Same docs:

const point3 = { x: 12, y: 26, z: 89 };
logPoint(point3); // no error
 
const rect = { x: 33, y: 3, width: 30, height: 80 };
logPoint(rect); // no error

To make the function safer, you should add a generic argument that extends Base:

function run<T extends Base>(arg: { prop: T }) {}

Now, in this function if you try to do the assignment to arg.prop, you will get an error:

function run<T extends Base>(arg: { prop: T }) {
  arg.prop = { // error here
    a: 1,
    b: 2,
  };
}

> Type '{ a: number; b: number; }' is not assignable to type 'T'.
'{ a: number; b: number; }' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint 'Base'.

This error means that since you expect something that extends Base it is not safe to assume that it is exactly Base.

To fix this error you can do the following:

function run<T extends Base>(arg: { prop: T }) {
  arg.prop = {
    ...arg.prop,
    a: 1,
    b: 2,
  };
}

This way you add all necessary fields of T and change the known ones from the Base (a and b).

As an alternative to spread you could assign a and b separately:

  arg.prop.a = 1;
  arg.prop.b = 1;

playground

Alternatively, you can restrict the run to accept pure Base again by using the generics:

function run<T extends Base>(arg: { prop: OnlyBase<T> }) {}

Now, let's define OnlyBase:

type OnlyBase<T extends Base> = {} extends Omit<T, keyof Base> ? T : never;

This type will check if the T will be an empty object after removing all of the keys of Base. If that's true that we can assume that T is base, otherwise return never to raise an error. Though, for the compiler this conditional won't change the type inference and you will still have to spread the arg.prop to remove the error described previously.

Testing:

const prop: Base = {
  a: 1,
  b: 2,
};

const originalObject = { prop };

run(originalObject);

const prop2: SubTest = {
  a: 1,
  b: 2,
  c: 3,
};

const originalObject2 = { prop2 };

run(originalObject2); // expected error

playground

TypeScript allows assignment of a subtype to an object property because it supports structural typing and allows for flexibility in object shapes. This behavior is intentional and part of TypeScript's design philosophy.

In your example, the run function accepts an argument of type { prop: Base }, which means it expects an object with a property named prop of type Base. When you pass originalObject to the run function, the type checker sees that originalObject.prop matches the expected type Base since SubTest is a subtype of Base. This is because SubTest extends Base by adding an additional property c.

At compile-time, TypeScript allows this assignment because it verifies that the provided object has at least the required properties of Base. However, during runtime, when you access originalObject.prop.c, you will encounter an error because the actual object does not have the c property defined.

This behavior is a trade-off between static type checking and runtime behavior. TypeScript's design aims to catch potential type errors early in the development process and provide a better development experience by providing type safety and code completion. However, it cannot guarantee runtime behavior since JavaScript is a dynamically-typed language.

To avoid runtime errors, you can refine the type of originalObject.prop to SubTest when passing it to the run function, like this:

run({ prop: prop });

By providing the specific type, the type checker will catch any inconsistencies at compile-time, and the runtime behavior will match the expected type.