react-crud-hook

React hook for CRUD-operations and record state management.

This package attempts to make it easier to perform CRUD-operations while also providing methods to set attributes and relationships on a record. Records should conform to the JSON:API specs - https://jsonapi.org/. The react-crud-hook package is fully typed and optimized to prevent unnecessary renders.

Installation

npm

npm install --save react-crud-hook

yarn

yarn add react-crud-hook

API

CrudManager

import { CrudManager } from 'react-crud-hook'

// First create a CRUD manager.
// The CRUD manager takes a single object with a promise for the createRecord, 
// updateRecord and deleteRecord attributes.
// You can use the extensions attribute to provide an object with custom extensions that
// will be returned in several callbacks later on as you perform CRUD-operations.
const manager = new CrudManager({
  createRecord: Promise<Record>,
  updateRecord: Promise<Record>,
  deleteRecord: Promise<RecordIdentifier>
  extensions: {
    dispatch: redux.dispatch,
    router: react.router,
    modal: modal
  }
})

Store

import { Store, Dispatcher, Reducer } from 'react-crud-hook'

// The store is not required as it is already provided by default. However if you like to customize how records are
// updated in the store you can provide your own Dispatcher and/or Reducer. 

const store = new Store({
  dispatcher: new Dispatcher(),
  reducer: new Reducer()
})

<CrudProvider/>

By default the provider will have a store, where it manages records and subscriptions. However, you can also pass one yourself.

import { CrudProvider } from 'react-crud-hook'

// Store is not required - it will have one by default
ReactDOM.render(
  <CrudProvider manager={manager} store={Store}>
    <App/>
  </CrudProvider>,
  rootElement
)

useCrud(record, options?)

import { useCrud } from 'react-crud-hook'

const record = {
  type: 'user',
  id: '1',
  attributes: {
    name: 'Exivity'
  }
}

const ReactComponent = () => {
  const record = useCrud(record)

  // Perform mutations on mount
  useEffect(() => {
    record
      .setAttribute('name', 'Exivity rocks!')
      .setAttribute('age', 2)
      .addHasMany('employees', { type: 'employee', id: '2' })
      .addHasMany('clients', { type: 'client', id: '7' })
      .addHasOne('CEO', { type: 'CEO', id: '2' })
      .resetAttributes('age')
      .save({ 

        // Use standard callback enriched with extensions to perform side tasks
        beforeUpdate: (record, extensions) => {
          return extensions.modal('Are you sure you want to proceed with this update?')
        },
        onUpdate: (record, extensions) => {
          extensions.router.push(`/user/${user.id}`)
        }

        // You can also include custom properties that will be passed on to the CRUD-functions 
        // as second argument, such as a include property:
        include: {
          .........
        }
      })
  }, [record.id])
   // State is managed via a functional pattern so you do not have to worry about race conditions etc. 
   // Make sure to use the id instead of record itself as dependencies for useEffect as the record will have a new reference
   // after you call a method on it. Also, if you rely on record attributes or relations in your effect, do not forget to put those
   // in dependencies array.

  // Or perform mutations on events
  return (
    <div>
      <input value={record.attributes.name}
        onChange={(e) => record.setAttribute('name', e.target.value)}/>
      <button onClick={record.save}> Click </button>
    </div>
  )
  
    // Use curried methods
    return (
      <div>
        <input value={record.attributes.name}
          onChange={record.setAttribute('name')}/>
        <button onClick={record.save}> Click </button>
      </div>
    )
}

options?

| Name | value | Description |:---- |:---------- |:----------- | unSubscribeDelay | number | When useCrud unmounts it deletes the associated record state from store - you can delay this with this option. | onUnSubscribe | (record) => void | This callback will be called when a record unSubscribes from store. Normally this happens when useCrud unmounts unless the unSubscribeDelay option has been given.

Methods

All the following methods, except for save and delete, can be curried by providing only the first argument.

| Name | Parameters | Description |:---- |:---------- |:----------- | setAttribute | attribute, value | Use setAttribute to update a record attribute. | addHasMany | relationship, RecordIdentifier | Use addHasMany to add a hasMany related record. | addHasOne | relationship, RecordIdentifier | Use addHasOne to add or replace a hasOne related record. | removeRelationship | relationship, relatedId | Use removeRelationship to remove a hasOne or hasMany related record. | reset | none | Use reset to reset all attributes and relationships to its initial value. | resetAttributes | string or string[] | Use resetAttributes to specifically reset attributes only. | resetRelationships | string or string[] | Use resetRelationships to specifically reset relationships only. | save | options? | Use save to persist a record - save will determine by the presence of an id whether to create or update. Alongside of the standard callbacks you can provide custom options which will be passed to the provider crud-functions as second argument. | delete | options? | Use delete to delete a record.

Parameter types

| Parameter | Type |:--------- |:---- | attribute | string | value | any | relationship | string | RecordIdentifier | { id: string, type: string } | RelatedId | string | options | { ...standardCallbacks, ...customOptions }

Standard callbacks and custom options

Callbacks are handled by the manager and enriched with the extensions you provide to the CrudManager. Custom options are passed to each crud function (provided to the CrudManager) as second argument. You can use the following callbacks:

| Callback | arguments | Description |:---------|:-----------|:----------- | beforeCreate | record, extensions | You can return a Promise that either returns a new record which it then will use for the create operation or a truthy or falsy value. Instead of a Promise you can also just directly return a truthy/falsy value A truthy value will let the operation proceed and a falsy value will abort it. | onCreate | record, extensions | onCreate will be called on fulfillment of the operation. | beforeUpdate | record, extensions | Works like beforeCreate. | onUpdate | record, extensions | Works like onCreate. | beforeDelete | record, extensions | Works like beforeCreate. | onDelete | recordIdentifier, extensions | Works like onCreate. | onError | error, record, extensions | If a operation (promise) catches, onError will be called.

License

MIT