State and State History

Overview 🎯📘💡

In the system, documents such as orders or customers are represented as JavaScript objects (e.g., {object: 'OrderDto'}). Each document contains a state property and a stateHistory property to track its lifecycle.

State Property 🔄📂⚙️

The state property represents the current status of a document. It can have one of the following values:

• active – The document is currently in use and operational.

• inactive – The document exists but is not currently active.

• archived – The document is stored for historical reference but is not active.

• deleted – The document is marked as removed but still exists in the system.

Important Note: ⚠️🛑🗂️

Our system never deletes any data. Instead, when a document is marked as deleted, it means that the user will no longer see the document, but it remains stored in the database for historical and auditing purposes.

Example: 📄🔍✅

{
  "object": "CustomerDto",
  "state": "inactive",
  "stateHistory": [
    {"state": "active", "setAt": "2025-01-01T00:00:00.000Z"},
    {"state": "inactive", "setAt": "2025-01-02T00:00:00.000Z"}
  ]
}

State History Property 📜🕒📊

The stateHistory property is an array that tracks all state changes of the document. Each entry in the array contains:

• state: The state the document was in.

• setAt: The timestamp when the state was set (in ISO format).

Example: 📋⏳📝

{
  "object": "CustomerDto",
  "state": "inactive",
  "stateHistory": [
    {"state": "active", "setAt": "2025-01-01T00:00:00.000Z"},
    {"state": "inactive", "setAt": "2025-01-02T00:00:00.000Z"}
  ]
}

How It Works ⚡🔄🔎

• The state property always reflects the latest state of the document.

• The stateHistory property logs all past state changes in chronological order.

• Developers should ensure that every state change is recorded in the stateHistory array.

Changing State 🔧⚙️🛠️

When updating the state of a document, developers must:

1. Append the previous state to the stateHistory array before updating the state property.

2. Update the state property to the new state.

Example of Updating State in JavaScript: 💻📌🖊️

enum StateEnum {
    active = 'active',
    inactive = 'inactive',
    archived = 'archived',
    deleted = 'deleted',
}

namespace ICustomer {

    interface DTO {
    
        object: 'CustomerDto';
        state: StateEnum;
        stateHistory: {
            state: StateEnum;
            setAt: string;
        }[];
        
    }

}

function updateState(document: object, newState: StateEnum) {
    // Ensure the state is actually changing
    if (document.state !== newState) {
        // Add current state to stateHistory before updating
        document.stateHistory.push({
            state: newState,
            setAt: new Date().toISOString()
        });
        
        // Update the state to the new value
        document.state = newState;
    }
}

// Example usage:
const customer = {
    object: 'CustomerDto',
    state: 'active',
    stateHistory: [{state: 'active', setAt: '2025-01-01T00:00:00.000Z'}]
};

updateState(customer, StateEnum.inactive);
console.log(customer);

Expected Output: 🖥️✅📄

{
  "object": "CustomerDto",
  "state": "inactive",
  "stateHistory": [
    {"state": "active", "setAt": "2025-01-01T00:00:00.000Z"},
    {"state": "inactive", "setAt": "2025-02-26T14:00:00.000Z"}
  ]
}

Developer Guidelines 📏✅🛠️

• Always ensure state changes are meaningful and necessary.

• Always append the previous state to stateHistory before updating the state property.

• Use ISO 8601 format for timestamps.

• Do not remove or alter previous stateHistory entries.

• Handle state transitions in a controlled and documented manner to maintain system integrity.

• Remember that deleted documents are not removed from the system; they are simply hidden from users.

By following these guidelines, developers can ensure a reliable and traceable state management system for documents. 🎯🚀📘