@vmelou/jsonapi-angular


Angular integration for @vmelou/jsonapi library. Provides mixins for easy integration with Angular's HttpClient and RxJS for JSON:API endpoints.

Table of Contents

- Installation
- Features
- Usage
- Basic Setup
- Using Mixins
- Handling Relationships
- Error Handling
- API Reference
- Examples
- Contributing
- Changelog
- License

Installation

``bash
npm install @vmelou/jsonapi @vmelou/jsonapi-angular


or

`typescript
import { BaseResource, JsonResource, JsonAttribute } from '@vmelou/jsonapi';

@JsonResource('authors')
export class Author extends BaseResource {
@JsonAttribute()
name = '';

@JsonAttribute(Date, 'created-at')
createdAt: Date = new Date();
}
`

$3

Create a service that uses the provided mixins through composition:

`typescript
import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { CreateMixin, RetrieveMixin, UpdateMixin, DeleteMixin, ListMixin } from '@vmelou/jsonapi-angular';
import { Observable } from 'rxjs';
import { Author } from './author.model';

@Injectable({ providedIn: 'root' })
export class AuthorService {
private createMixin: CreateMixin;
private retrieveMixin: RetrieveMixin;
private updateMixin: UpdateMixin;
private deleteMixin: DeleteMixin;
private listMixin: ListMixin;
private endpoint = 'authors';

constructor(http: HttpClient) {
this.createMixin = new CreateMixin(http, this.endpoint, Author);
this.retrieveMixin = new RetrieveMixin(http, this.endpoint, Author);
this.updateMixin = new UpdateMixin(http, this.endpoint, Author);
this.deleteMixin = new DeleteMixin(http, this.endpoint, Author);
this.listMixin = new ListMixin(http, this.endpoint, Author);
}

list(query?: { [key: string]: string }): Observable> {
return this.listMixin.list(query);
}

create(data: Partial): Observable {
return this.createMixin.create(data);
}

retrieve(id: string, include: string[] = []): Observable {
return this.retrieveMixin.retrieve(id, include);
}

update(id: string, data: Partial): Observable {
return this.updateMixin.update(id, data);
}

delete(id: string): Observable {
return this.deleteMixin.delete(id);
}

// Custom endpoint example
retrieveProfile(id: string): Observable {
return this.retrieveMixin.retrieve(${id}/profile);
}
}
`

Now you can use the service in your components:

`typescript
@Component({
selector: 'app-authors',
template:

constructor(private authorService: AuthorService) {}
}
`

$3

The mixins automatically handle relationships defined in your models:

`typescript
@JsonResource('books')
export class Book extends BaseResource {
@JsonAttribute()
title = '';

@JsonAttribute(Author)
author?: Author;

@JsonAttribute(Author, 'co-authors')
coAuthors: Author[] = [];
}

@Injectable({ providedIn: 'root' })
export class BookService {
private retrieveMixin: RetrieveMixin;
private endpoint = 'books';

constructor(http: HttpClient) {
this.retrieveMixin = new RetrieveMixin(http, this.endpoint, Book);
}

getBookWithAuthor(id: string): Observable {
return this.retrieveMixin.retrieve(id, ['author', 'co-authors']);
}

// Custom endpoint example
getBookReviews(id: string): Observable {
return this.retrieveMixin.retrieve(${id}/reviews);
}
}
`

$3

All mixins include built-in error handling that converts JSON:API error responses to ApiError objects:

`typescript
this.bookService.create(newBook).subscribe({
next: (book) => console.log('Book created:', book),
error: (errors: ApiError[]) => {
errors.forEach((error) => {
console.error(Error: ${error.title} - ${error.detail});
});
},
});
`

API Reference

$3

- ListMixin: List resources with pagination and filtering

- list(query?: { [key: string]: string }, url?: string): Observable>

- CreateMixin: Create new resources

- create(data: Partial): Observable

- RetrieveMixin: Retrieve single resources

- retrieve(id: string, include: string[] = []): Observable

- UpdateMixin: Update existing resources

- update(id: string, data: Partial): Observable

- DeleteMixin: Delete resources
- delete(id: string): Observable

$3

The list method supports various query parameters:

`typescript
// Pagination
service.list({ 'page[number]': '1', 'page[size]': '10' });

// Filtering
service.list({ 'filter[name]': 'John' });

// Including relationships
service.list({ include: 'author,co-authors' });

// Sorting
service.list({ sort: '-created-at,name' });
`

Examples

$3

`typescript
@Component({
template:

deleteBook(book: Book) {
this.bookService.delete(book.id).subscribe({
next: () => console.log('Book deleted'),
error: (errors) => console.error('Failed to delete book:', errors),
});
}
}
`

$3

`typescript
interface PaginationMeta {
pagination: {
count: number;
page: number;
pages: number;
};
}

@Component({
template:

loadPage(url: string | null) {
if (url) {
this.results$ = this.bookService.list({}, url);
}
}
}
``

Contributing

We welcome contributions! Please see our Contributing Guidelines for more details on how to get involved.

Changelog

Detailed changes for each release are documented in the CHANGELOG.md file.

License

MIT