FeathersModel Instances #

This page covers the ways you can create FeathersModel instances and gives details about the FeathersModel Instance interface.

Related reading:

• FeathersModel Static API
• FeathersModel Stores
• useService API

Creating FeathersModel Instances #

There are two ways to create FeathersModel instances:

• Directly with useFeathersModel

• Upgrading BaseModel instances with useFeathersInstance

With useFeathersModel #

Once you've created a FeathersModel, you can pass it data to create an instance:

import { Task } from '../models/task'

const task = Task({ description: 'Do the dishes' })

// Send it to the Feathers API server
await task.save()

You also get the correct types if you create in save all at once, or use any of the instance methods.

const task = await Task({ description: 'Do the dishes' }).save()

Upgrading a BaseModel #

You can use the useFeathersInstance utility in a Model Function to add FeathersModel instance methods to your data.

Built on BaseModel #

All FeathersModel instances also include the properties and methods found on BaseModel instances. This page only covers the methods that are unique to FeathersModel instances.

Instance Properties #

isPending #

Reads store state and evaluates to true if any type of request is pending for the instance.

import { Task } from '../models/task'

const task = Task({ description: 'Do the dishes' })
const request = task.save() // or any Feathers method
console.log(task.isPending) // --> true

isSavePending #

Reads store state and evaluates to true if there is a pending create or patch request for the instance.

task.isSavePending // --> boolean

isCreatePending #

Reads store state and evaluates to true if there is a pending create request for the instance.

task.isCreatePending // --> boolean

isPatchPending #

Reads store state and evaluates to true if there is a pending patch request for the instance.

task.isPatchPending // --> boolean

isRemovePending #

Reads store state and evaluates to true if there is a pending removerequest for the instance.

task.isRemovePending // --> boolean

Feathers Methods #

The following methods are available on FeathersModel instances:

save(params) #

The save method is a convenience wrapper for the create/patch methods. If the record has no idField, the instance.create()method will be used. Theparams argument will be used in the Feathers client request. See the Feathers Service docs, for reference on where params are used in each method.

import { Task } from '../models/task'

// Call addToStore to get a reactive Vue object
const task = Task({ description: 'Do something!' }).addToStore()

await task.save() // --> Creates the task on the server.

Once the create response returns, the record will have an idField assigned by the server. Most databases give each record an id. Others use a different field. For example, MongoDB uses _id. If you call instance.save() again, the method will call instance.patch(). Which method is used depends solely on whether the data has a proeprty matchin ghte idField in the service store.

When calling save() on a clone, you can use special params to handle patch diffing.

create(params) #

The create method calls the create action (service method) using the instance data. The params argument will be used in the Feathers client request. See the Feathers Service docs, for reference.

You might not ever need to use .create(), but can instead use the .save() method. Let Feathers-Pinia call create or patch.

const task = Task({ description: 'Do something!' })

await task.create() // --> Creates the task on the server using the instance data

patch(params) #

The patch method calls the patch action (service method) using the instance data. The instance's id field is used for the patch id. The params argument will be used in the Feathers client request. See the Feathers Service docs, for reference.

Similar to the .create() method, you might not ever need to use .patch() if you just use .save() and let Feathers-Pinia figure out how to handle it.

const task = Task({ id: 1, description: 'Do something!' })
task.description = 'Do something else'
await task.patch() // --> Sends a `patch` request the with the id and description.

When calling save() on a clone, you can use special params to handle patch diffing.

remove(params) #

Patch Diffing #

Patch diffing, which originated in Feathers-Vuex, is now back in Feathers-Pinia with a smarter, faster algorithm that will work for any scenario you can dream up.

Diffing only occurs on patch requests (and when calling instance.save() calls a patch).

// clone a record
const clone = user.clone()
// make changes
clone.name = 'Feathers is Amazing!'
// save
await clone.save(). // --> Only the changed props go to the server!

Customize the Diff #

You can use the diff option to customize which values are compared. Only props that have changed will be sent to the server.

// string: diff only this prop
await clone.save({ diff: 'teamId' )

// array: diff only these props
await clone.save({ diff: ['teamId', 'username'] )

// object: merge and diff these props
await clone.save({ diff: { teamId: 1, username: 'foo' } )

// or turn off diffing and send everything
await clone.save({ diff: false })

Always Save Certain Props #

If there are certain props that need to always go with the request, use the with option:

// string: always include this prop
await clone.save({ with: 'teamId' )

// array: always include these props
await clone.save({ with: ['teamId', 'username'] )

// object: merge and include these props
await clone.save({ with: { teamId: 1, username: 'foo' } )

Specify Patch Data #

When calling .save() or .patch(), you can provide an object as params.data, and Feathers-Pinia will use it as the patch data. This bypasses the diff and with params.

const task = Task({ description: 'Do Something', isComplete: false })
await task.patch({ data: { isComplete: true } })