@rest-api/react-models

Make your React project easier to maintain with this package.

Benefits:

You will gain a more typed project (if you are using Typescript)
All ajax calls are stored on redux, your endpoint is only called on necessary
Better structure on your project

Caution: if you have some random typescript error (pex: ts2589) on creating or editing models, kill the process and restart npm start (on Visual Studio Code restart program).

Features

Added nullable argument to schema fields
Added initialized variable for all requests (if not initialized, is not requested)

Major changes

From v1

Upgraded typescript version and needs your proyect version >=3.9.3 (and react-scripts >= 3.4.1, if you don't eject your project)
Required and idOnly don't need to import from library since upgraded typescript version
A model on a schema represents the schema of model (for represent the primary key, needs to pass idOnly argument)
Connect methods deleted (deprecated on v1)
Added more flexibility on models generation adding methods ("getSubModelWithKey" and "getSearchSubModel") to models

From v0

On model creation don't need to pass a model name. This major includes a refactor and some bug fixes and features.

File structure

This code examples follows this src structure:

src
└-- models
|   └-- bookModel.ts
|   └-- libraryModel.ts
└-- containers
|   └-- bookContainer.tsx
|   └-- libraryContainer.tsx
└-- views
|   └-- bookView.tsx
|   └-- libraryContainer.tsx
└-- index.tsx

Provider

First of all you need to insert on your index.tsx the provider from application.

...
import { getProvider } from  '@rest-api/react-models';

const ReactModelsProvider = getProvider();


ReactDOM.render(<ReactModelsProvider>
    <App />
</ReactModelsProvider>, document.getElementById('root'));

Declaring models

Declare the models of your application, given a Schema, an id (need to be required field) and a base url:

import { Model, Schema } from  '@rest-api/react-models'

const librarySchema = Schema({
    id: {
        type: Number,
        required: true
    },
    name: String
})
export  default  new  Model(librarySchema, 
    'id', // must be declared as required, string or number and not array or null
    '/api/library')

You can use complex objects on a Schema simplier creating subschemas:

import { Schema } from  '@rest-api/react-models'

const testSchema = Schema({
    subSchema: Schema({
        id: { type: String },
        name: String
    })
})

Represent a field which can be null:

import { Schema } from  '@rest-api/react-models'

const testSchema = Schema({
    nullableField: { 
        type: String, 
        nullable: true, 
        required: true 
    }
})

For a model with metadata, you can represent with following arguments (declaring the data that endpoint sends):

import { Model, Schema } from  '@rest-api/react-models'

const librarySchema = Schema({
    id: {
        type: Number,
        required: true
    },
    name: String
})
export  default  new  Model(librarySchema, 
    'id', 
    '/api/library',
Schema({
    count: {
        type: Number,
	required: true
    },
    items: [{
        type: librarySchema,
	required: true
    }]
},
data => data.items,
({items, ...metadata}) => metadata,
{} //here optional opts (trailingSlash and headers)
)

And foreign keys of your model can be representated:

import { ModelType, ModelPopulatedType, Schema, Model } from  '@rest-api/react-models'
import libraryModel from './libraryModel'

const bookSchema = Schema({
    id: { type: Number, required: true },
    name: { type: String, required: true },
    description: String,
    library: {
        type: libraryModel,
        required: true,
        idOnly: true
    }
})
export type BookType = ModelType<typeof bookSchema>
export type BookPopulatedType = ModelPopulatedType<typeof bookSchema>
export default new Model(bookSchema, 'id', '/api/book')

An option can be passed to model declaration in order to works with django "trailing slash" or pass custom headers:

new Model(bookSchema, 'id', '/api/book', { trailingSlash: true, headers: { Authorization: "Basic xxxx" } })

New methods of model

If you has an endpoint on a different url that represents same object, now you can use your declared model

getSubModelWithKey method

In order to get an object by a key (not an id, but is unique) this is your method Simple usage:

import bookModel from './bookModel'
export default bookModel.getSubModelWithKey('name', '/api/book/name') 

//url is optional, if not provided will be used url from bookModel

Full control on your url:

import bookModel from './bookModel'
import { Schema } from '@rest-api/react-models'
const optSchema = Schema({ 
    project: { 
        type: Number, 
        required: true 
    }
})
export default bookModel.getSubModelWithKey(optSchema, 'name', ({project}) => `/api/book/${project}/name`)

getSearchSubModel method

This method is in order to work as "useGet" or "useGetPopulated", but in other url

Simple usage:

import bookModel from './bookModel'
export default bookModel.getSearchSubModel('api/book/hector')

Full control on your url:

import bookModel from './bookModel'
import { Schema } from '@rest-api/react-models'
const optSchema = Schema({ 
    author: { 
        type: String,
        required: true 
    }
})
export default bookModel.getSearchSubModel(optSchema, ({author}) => `/api/book/${author}`)

Using on the container

Simple usage

Once you have created a model, you can use it on a container!

Fist clean mode using Typescript, using a hook:

import  React  from  'react'

import  bookModel  from  '../models/bookModel'
import  BookView  from  '../views/bookView'


export default () => {
	const { items, loading, error, initialized } = bookModel.useGet()
    if (!initialized) <p>Request not fetched</p>
	if (error) return  <p>There are an error with the request</p>
	if (loading) return  <p>Loading...</p>
	return  <ul>{
		items.map(i  =>  <BookView  name={i.name}  />)
	}</ul>
}

Populate items

This feature populate foreign key if these ones aren't fetched. It's recommended to fetch beore this call the objects using useGet (pex: on Apps initialization). The ajax method will be called only on necessary (if there are some object not fetched).

You can populate items with a simple usage (you need to check if it's populated, if you want to use a placeholder):

import React from 'react'

import bookModel from '../models/bookModel'

export default () => {
    const { loading, error, ...result } = bookModel.useGetPopulated()

    if (error) return <p>There are an error with the request</p>
    if (loading) return <p>Loading...</p>
    return <table>
	<thead>
	    <tr>
		<th>Id</th>
		<th>Name</th>
		<th>Library name</th>
	    </tr>
	</thead>
	<tbody>
	    {
		result.populated ?
		result.items.map(i => <React.Fragment key={i.id}>
		    <td>{i.id}</td>
		    <td>{i.name}</td>
		    <td>{i.library.name}</td>
		</React.Fragment>) :
		result.items.map(i => <React.Fragment key={i.id}>
		    <td>{i.id}</td>
		    <td>{i.name}</td>
		    <td>{i.library.name ?? 'Loading ...'}</td>
		</React.Fragment>)
	    }
	</tbody>
    </table>
}

Use methods (POST, PUT, PATCH, DELETE)

In order to access to one of those methods, select the correct hook (usePost, usePut, usePatch or useDelete)

import React from 'react'

import { ModelType, HttpError } from '@rest-api/react-models'
import bookModel from '../models/bookModel'
import { useHistory } from 'react-router-dom'

export default () => {
    const post = bookModel.usePost()
    const [data, setData] = React.useState<ModelType<typeof bookModel>|null>(null)
    const history = useHistory()
    const [error, setError] = React.useState<HttpError|null>(null)
    
    function handleSubmit(ev){
        ev.preventDefault()
        if(data)
            post(data, (err, res) => {
                if(err) //there are an error with request
                    return setError(err)
                history.push('to the new path')
            })
    }

    return ...
}

@rest-api/react-models