Prefer Returning Objects to Literal Types

Let's say you're designing an API that returns the awards a user has earned.

A first pass might return a list of strings:

function getUserAwards(user: User): string[] { ... }

console.log(getUserAwards(joe)); // ["rockstar", "10x-engineer", ...]

That works, but it also makes the contract fragile. A string can only say so much.

A better shape is to return objects:

interface Award {
  name: string;
}

function getUserAwards(user: User): Award[] { ... }

console.log(getUserAwards(joe)); // [{ name: "rockstar" }, { name: "10x-engineer" }, ...]

That extra wrapper may feel unnecessary when the object only has one property, but it buys you room to grow.

Your API can evolve without breaking callers

Imagine you want to add the timestamp for when each award was granted.

If your API returns string[], you now have an awkward choice:

• add a separate endpoint for award timestamps, or
• change the existing response shape and break every caller.

If the API already returns Award[], you can extend the model naturally:

interface Award {
  name: string;
  awardedAt: Date;
}

Callers that only care about the award name can ignore the new field. Callers that need more detail can opt in without a migration.

Objects communicate domain meaning

Code is easier to work with when names reflect the business language. If the thing you are returning is an award, return Award[]. If it is a post, return Post[]. If it is an invoice, return Invoice[].

That sounds obvious, but it matters. A string could mean anything. An Award carries intent, and that intent makes the codebase easier to read, extend, and discuss.

A simple rule of thumb

Prefer objects when the value has identity, may gain fields later, or belongs to a real domain concept. Keep literal types for truly atomic data, such as IDs, slugs, or short enumerations.

That balance gives you a cleaner API today and a safer one tomorrow.