State machines for paged crud components

The Paged CRUD state machines encapsulate logic for managing paginated data and entity operations (create, read, update, delete) within a Supabase database. These state machines handle form submissions, data loading, selection, filtering, sorting, and pagination.

Key Concepts:

1. Paged Entity State Machines: Manage entities in a paginated format, handling both list and detail operations.
2. Form Handling: Manage form state, including validity and dirty tracking.
3. Selection & Deletion: Enable selecting and deleting multiple items in paginated lists.
4. Routing: Handle routing after actions such as saving or deletion.

1. PagedCrudEntityCreateStateMachine: Managing Entity Creation in a Paged Context

The PagedCrudEntityCreateStateMachine manages the process of creating new entities in a paginated Supabase database. It tracks form validity, handles submission, and provides navigation after the entity is created.

Key Responsibilities:

• Form State: Tracks whether the form is dirty or valid.
• Entity Creation: Maps form data to the structure required for database insertion.
• Navigation: Navigates back after entity creation, with optional callbacks.

Example Use Case: Adding a New Idea

Smart Component for Adding a New Idea:

export class IdeasAddSmartComponent {
  readonly #pagedIdeaStateMachine = inject(PagedIdeaStateMachine);  // Injecting the state machine for ideas

  // Function to map form values to the database structure
  readonly #mapFormToEntity = (form: ValidIdeaFormModel): IdeaInsert => {
    return {
      name: form.name,
      description: form.description,
      author_id: form.authorId,
    };
  };

  // State machine for managing the creation of a new idea
  protected readonly createState = new PagedCrudEntityCreateStateMachine<
    Database,
    'ideas',
    ValidIdeaFormModel
  >(this.#pagedIdeaStateMachine, this.#mapFormToEntity);

  // Form validation rules
  protected readonly suite = ideaFormValidations;
}

Key Functions:

• #mapFormToEntity(): Converts form data to the required format for inserting an idea into the database.
• createState.save(): Saves the form data, creates the idea, and navigates back after completion.

---

2. PagedCrudEntityListStateMachine: Managing Paginated Lists

The PagedCrudEntityListStateMachine manages the list of entities in a paginated format, handling operations like filtering, selection, sorting, and deletion.

Key Responsibilities:

• Pagination: Loads different pages of the list based on user interaction.
• Selection & Deletion: Enables selecting individual or multiple items and handling batch deletions.
• Sorting: Supports sorting by various columns, with ascending or descending order.
• Querying: Filters the list based on a search query.

Example Use Case: Managing a List of Products

Smart Component for Displaying a List of Products:

export class ProductsSmartComponent {
  readonly #pagedIdeaStateMachine = inject(PagedIdeaStateMachine);  // Injecting the state machine for ideas

  // Signal representing whether the data is loading
  protected readonly loading = this.#pagedIdeaStateMachine.loading;

  // State machine for managing the list of ideas (products)
  protected readonly listState = new PagedCrudEntityListStateMachine<
    Database,
    'ideas'
  >(this.#pagedIdeaStateMachine, 'name');  // Sorting the list by the "name" column

  // Method to load a specific page
  protected loadPage(event: number): void {
    this.listState.loadPage(event);
  }
}

Key Functions:

• loadPage(): Loads a specific page of items when the user interacts with pagination controls.
• listState.toggleSorting(): Toggles sorting by different columns in ascending or descending order.

---

3. PagedCrudEntityUpdateStateMachine: Managing Entity Updates in a Paged Context

The PagedCrudEntityUpdateStateMachine class is responsible for managing the update process of an existing entity within a paged context. It handles form state, tracks the loading and deletion of the entity, and manages navigation after saving or deleting the entity.

Key Responsibilities:

• Form State: Tracks the form's dirty and valid states.
• Entity Loading: Loads an entity for updating based on the route parameters.
• Entity Update: Maps form data to the structure required for updating the entity in the database.
• Navigation: Redirects after updating or deleting the entity.

Example Use Case: Updating an Idea

Smart Component for Updating an Idea:

export class IdeasUpdateSmartComponent {
  readonly #pagedIdeaStateMachine = inject(PagedIdeaStateMachine);  // Injecting the state machine for ideas

  readonly #mergeEntityWithForm = (
    entity: IdeaRow,
    formValue: Partial<ValidIdeaFormModel>
  ): ValidIdeaFormModel => {
    return {
      ...formValue,
      name: entity.name,
      description: entity.description,
    };
  };

  readonly #mapFormToEntity = (form: ValidIdeaFormModel): IdeaUpdate => {
    return {
      id: this.#pagedIdeaStateMachine.id(),  // Get the entity ID from the state
      name: form.name,
      description: form.description,
    };
  };

  // State machine for managing the update of an idea
  protected readonly updateState = new PagedCrudEntityUpdateStateMachine<
    Database,
    'ideas',
    ValidIdeaFormModel
  >(
    this.#pagedIdeaStateMachine,
    this.#mergeEntityWithForm,
    this.#mapFormToEntity
  );
}

Key Functions:

• #mergeEntityWithForm(): Merges the loaded entity data with the current form values.
• updateState.save(): Saves the updated form data and updates the entity in the database.

---

Core Methods and Signals

PagedCrudEntityCreateStateMachine

• setFormValid(event: boolean): Sets the validity of the form.
• setFormDirty(event: boolean): Sets whether the form has been modified.
• setFormValue(event: Partial<K>): Updates the form value.
• save(): Saves the form data as a new entity in the database.
• goBack(): Navigates back to the previous route after saving.

PagedCrudEntityListStateMachine

• loadPage(event: number): Loads a specific page of items.
• toggleSorting(sortBy: keyof DatabaseSchema['public']['Tables'][TableName]['Row']): Toggles sorting by a column.
• onDeleteSelected(): Marks selected items for deletion.
• performRemove(): Deletes the marked items from the database.

PagedCrudEntityUpdateStateMachine

• setFormValid(event: boolean): Sets the validity of the form.
• setFormDirty(event: boolean): Sets whether the form has been modified.
• save(): Saves the updated entity data.
• performRemove(): Deletes the current entity and navigates back.

---

Conclusion

The Paged CRUD state machines simplify the management of paginated data and form handling for creating, updating, and listing entities in Supabase databases. They offer an easy-to-use API for managing form state, data loading, selection, and deletion in paginated contexts, providing developers with a consistent and reusable framework for CRUD operations in Angular applications.