Improve Memory support for role based creeps and the like

[Jomik]

Problem

It is currently impossible to have memory types that make use of union types with type guards to narrow properties.
Assume we have the following types for our various roles.

interface MinerMemory {
  sourceId: Id<Source>;
}
interface BuilderMemory {
    targetId?: Id<ConstructionSite>;
}
interface HaulerMemory {
    targetId?: Id<AnyStructure>;
}

There is currently two ways to type this:

// The method using optional properties
interface CreepMemory {
  sourceId?: Id<Source>;
  targetId?: Id<ConstructionSite> | Id<AnyStructure>;
}
// Or using a nested property
type AttachRole<T extends string, O extends object & Partial<Record<"role", never>>> = { role: T } & O;
interface CreepMemory {
  actualMemory:
    | AttachRole<'miner', MinerMemory>
    | AttachRole<'builder', BuilderMemory>
    | AttachRole<'hauler', HaulerMemory>;
}

The first method has the obvious issue of requiring unnecessary checks for undefined, or unsafe use of the non-null assertion operator, the type also get's rather large, and you may end up reusing a property for the a lot of different purposes with various types.
The second method adds an extra unnecessary level of nesting, but does allow you to safely access memory based on the role property that AttachRole adds.

The solution

This PR adds a solution that allows us to fully control the memory type.

type MyCreepMemory =
  | Brand<'miner', MinerMemory>
  | Brand<'builder', BuilderMemory>
  | Brand<'hauler', HaulerMemory>;

interface Memory {
  creeps: Record<string, MyCreepMemory>;
}

const creep = Game.creeps[name];
if (creep.memory.role === 'hauler') {
  // creep.memory is now of type HaulerMemory
}

There is a caveat. This solution prevents us from merging CreepMemory and the likes from multiple files.
In my opinion it shouldn't be done anyway, and isn't necessary - you should just import them and add them to the *Memory type above.

Other than that, we should have full support of what could be done before.

Try it out

Use either of the below commands, depending on your package manager

npm install -D @types/screeps@jomik/typed-screeps#flexible-memory

yarn add -D @types/screeps@jomik/typed-screeps#flexible-memory

This should update your package.json to contain a reference to my branch:

    "@types/screeps": "jomik/typed-screeps#flexible-memory",

Checklists

• Test passed
• Coding style (indentation, etc)
• Edits have been made to src/ files not index.d.ts
• Run npm run dtslint to update index.d.ts

[admon84]

I think this change offers a great opportunity to define stronger types for creeps memory which leads to cleaner code.

In my opinion, if the examples in the tests used role: "harvester"/"builder" instead of type: "foo"/"bar" they would be more clear. Since those are the first two roles introduced in the tutorial, it would create some consistency with the basics.

It would be nice to add these examples to the Readme for more visibility because it seems like better practice to define strong types this way compared to the alternative options.

Great work!

[Sca1ey]

I’ve been testing this for a few days now and find this is much better than the previous lists of optional properties. I can’t see the advantage of the Brand<> part over the explicit typing, but then my TS experience is limited to Screeps.

[Jomik]

I’ve been testing this for a few days now and find this is much better than the previous lists of optional properties. I can’t see the advantage of the Brand<> part over the explicit typing, but then my TS experience is limited to Screeps.

No real reason to use Brand other than being more DRY I suppose. It prevents you from having a type in your "brand" key, role in the example case.

[Sca1ey]

Just trying to work out the Brand<> part - but your example in the description seems incomplete, the Brand type isnt' defined?
Should be: type Brand<T,V> = {type:T} & V although maybe Role is a bit more creepy than Brand?

[Jomik]

Just trying to work out the Brand<> part - but your example in the description seems incomplete, the Brand type isnt' defined? Should be: type Brand<T,V> = {type:T} & V although maybe Role is a bit more creepy than Brand?

Ah, sorry. Yes, that is correct. I will add it as a note, but currently I define it as seen here

typed-screeps/dist/screeps-tests.ts

Line 22 in 896ac3f

type Brand<T extends string, O extends object & Partial<Record<"role", never>>> = { role: T } & O;

Pushed a change and named it AttachRole