Implementing Type-State Programming in TypeScript

Type-state programming is a paradigm where an object's behavior and available methods depend on its current state, enforced at compile time. This helps prevent bugs by ensuring that operations are only performed when an object is in a valid state. This challenge asks you to implement a basic type-state system for managing a simplified resource, like a file handle, in TypeScript.

Problem Description

Your task is to create a system that models a resource (e.g., a connection, a file) that can exist in different states. The states should restrict which operations can be performed on the resource, with these restrictions enforced by the TypeScript type system.

Specifically, you need to:

1. Define distinct states: Create types that represent the different states of a resource (e.g., Closed, Open, Reading, Writing).
2. Create a resource class: Design a class that encapsulates the resource and its current state.
3. Implement state-dependent methods: Methods should only be callable when the resource is in a specific state. Attempting to call a method in an invalid state should result in a compile-time error.
4. Implement state transitions: Provide methods to transition the resource from one valid state to another. These transitions should also be type-safe.

The goal is to prevent common errors like trying to read from a closed resource, writing to a resource that's only meant for reading, or forgetting to close a resource.

Examples

Example 1: Basic Resource Lifecycle

Imagine a Connection that can be Closed or Connected.

// Initial state: Closed
const connection = new Connection();

// Trying to send data when closed (should be a compile-time error)
// connection.send('hello'); // Error: Property 'send' does not exist on type 'Connection<Closed>'

// Opening the connection
const connectedConnection = connection.open(); // connectedConnection is now of type Connection<Connected>

// Sending data when connected (should be valid)
connectedConnection.send('hello');

// Closing the connection
const closedConnection = connectedConnection.close(); // closedConnection is now of type Connection<Closed>

Example 2: Resource with Multiple Operations

Consider a FileHandle that can be Closed, Readable, or Writable.

type FileState = 'Closed' | 'Readable' | 'Writable';

class FileHandle<State extends FileState = 'Closed'> {
    private state: State;
    private content: string = "";

    constructor(initialState: State = 'Closed' as State) {
        this.state = initialState;
    }

    open(mode: 'read' | 'write'): State extends 'Closed' ? FileHandle<"Readable" | "Writable"> : never {
        if (this.state !== 'Closed') {
            throw new Error("File is already open.");
        }
        if (mode === 'read') {
            return new FileHandle('Readable') as any; // Type assertion needed for transition
        } else {
            return new FileHandle('Writable') as any; // Type assertion needed for transition
        }
    }

    read(): State extends 'Readable' ? string : never {
        if (this.state !== 'Readable') {
            throw new Error("File is not in readable mode.");
        }
        return this.content as any; // Type assertion needed for return type
    }

    write(data: string): State extends 'Writable' ? void : never {
        if (this.state !== 'Writable') {
            throw new Error("File is not in writable mode.");
        }
        this.content = data;
    }

    close(): State extends 'Readable' | 'Writable' ? FileHandle<'Closed'> : never {
        if (this.state === 'Closed') {
            throw new Error("File is already closed.");
        }
        return new FileHandle('Closed') as any; // Type assertion needed for transition
    }
}

// Usage
const file = new FileHandle(); // Implicitly Closed

// const data = file.read(); // Compile-time error: Property 'read' does not exist on type 'FileHandle<"Closed">'

const readableFile = file.open('read');
const fileContent = readableFile.read(); // Valid

// readableFile.write("new data"); // Compile-time error: Property 'write' does not exist on type 'FileHandle<"Readable">'

const writableFile = file.open('write'); // Error: Cannot call 'open' on 'Closed' if it was already opened as 'read' (This is a simplification for the challenge, complex interdependencies are out of scope)

// For the purpose of this challenge, assume a fresh file handle for each example.
const freshFile = new FileHandle();
const readableFile2 = freshFile.open('read');
const content = readableFile2.read();
const closedFile2 = readableFile2.close();

const freshFile2 = new FileHandle();
const writableFile2 = freshFile2.open('write');
writableFile2.write("some data");
const closedFile3 = writableFile2.close();

Example 3: Invalid State Transition

// Assume the FileHandle class from Example 2

const file = new FileHandle();
const readableFile = file.open('read');

// Trying to close a file that is already closed (compile-time error if we had a 'Closed' type explicitly)
// const alreadyClosed = readableFile.close().close(); // This would fail if the return type of close was not specific enough

// The core challenge is to make the *transition* and *method calls* type-safe.
// The provided examples illustrate successful state transitions and valid method calls.
// The compilation errors shown in comments are what you aim to achieve.

Constraints

• The resource state transitions must be exclusively managed by the type system.
• You should aim to minimize the use of any as much as possible. If any is absolutely necessary for a specific, well-justified reason (like complex conditional types for transitions), it should be clearly commented.
• The solution should be implemented in TypeScript.
• The focus is on demonstrating the type-state concept, not on extensive error handling within the methods themselves (e.g., handling file system errors). Runtime Error throws are acceptable for invalid operations that the type system couldn't catch due to runtime logic.

Notes

This problem explores advanced TypeScript features such as:

• Generic Types: To parameterize the state of your resource.
• Conditional Types: To define return types and method availability based on the current state.
• Mapped Types/Intersection Types (optional): Might be useful for more complex state definitions.

Consider how to represent the states and how to use them in conditional types to restrict method calls. Think about how a method that returns a new state should inform the type system about the resulting state. You might need to leverage as type assertions judiciously for state transitions, but the goal is to make the overall interaction type-safe from the consumer's perspective.