9.4.0 • Published 7 years ago

@citygro/vdata v9.4.0

Weekly downloads
1
License
Apache-2.0
Repository
-
Last release
7 years ago

@citygro/vdata -- reactive query model

build status coverage report npm downloads npm version license

yarn add @citygro/vdata

if you are building a webpack or babel project you can make @citygro/vdata smaller (via tree shaking and chunking) by aliasing this package to node_modules/@citygro/vdata/src/index.js rather than using our commonjs bundle.

Modules

Constants

Functions

export default { mixins: createMixinForItemById({ idPropertyName: 'userId', collectionName: 'users', localPropertyName: 'user', requestOptions: { capture: false } }) }

export default { mixins: UserById , props: { userRequestOptionsOverride: { default () { return { capture: this.$session.hasPermissionToEditUsers() } } } } // ... }

createMixinForItemById

Store

handleChange

Kind: global constant

ParamType
valueobject
diffobject

handleKeyChange

Kind: global constant

ParamType
valueobject
keystring
diffobject

handleArrayChange

Kind: global constant

ParamType
valueobject
inumber
diffobject

handleArrayKeyChange

Kind: global constant

ParamType
valueobject
inumber
keystring
diffobject

pushToArray

Kind: global constant

ParamType
valuearray
diffobject

pushToArrayKey

Kind: global constant

ParamType
valueobject
keystring
diffobject

removeFromArray

Kind: global constant

ParamType
valuearray
inumber

removeFromArrayKey

Kind: global constant

ParamType
valueobject
inumber
keystring

createDataFlowMixin(valueProp)

create a dataflow mixin for a given value prop.

a 'value' dataflow implements the v-model interface.

custom dataflows follow a pattern: methods are prefixed with the valueProp name and update:${valueProp} is emitted.

Kind: global function

ParamTypeDescription
valuePropstringbind dataflow to this prop

add(vm)

register handlers that will run on datastore events

Kind: global function

ParamType
vmVue.Component

createMixinForItemById(options) ⇒ object

create a mixin that configures a vm to manipulate a single record. you can use a prop to ask for a record by id or specify a template to create a new record that is pre-populated with some initial state.

// @/queries/UserById.js
import {createMixinForItemById} from '@citygro/vdata'

export default {
  mixins: [
    createMixinForItemById({
      idPropertyName: 'userId',
      collectionName: 'users',
      localPropertyName: 'user',
      requestOptions: {
        capture: false
      }
   })
  ]
}

a vm which consumes this mixin will have the following props, methods, data, &c. it will also be configured to react to changes to data in the store and update itself accordingly.

{
  props: {
    userid: String,
    userRequestOptionsOverride: Object
  },
  data: {
    user: Object,
  },
  methods: {
    userSave: Function,
  },
  computed: {
    asyncLoading: Boolean,
    userLoading: Boolean,
    userHasChanges: Boolean
  }
}

@/queries/UserById defines a query that fetches and captures the initial state for a user record. lets say we have a particular editor that provides read-only access to a particular resource for some users and read/write access for others.

for the case where the editor should be read/write we can default some props in the vm to change its behavior depending on the permissions of the current user.

// UserEditor.js
import UserById from '@/queries/UserById'

export default {
  mixins: [
    UserById
  ],
  props: {
    userRequestOptionsOverride: {
      default () {
        return {
          capture: this.$session.hasPermissionToEditUsers()
        }
      }
    }
  } // ...
}

Kind: global function
Returns: object - item-by-id query mixin

ParamTypeDefaultDescription
optionsobject
options.collectionNamestring
options.localPropertyNamestringthe vm data where the result of the query will be stored
options.idPropertyNamestring"id"the name of the prop you will use to specify the id of the requested record
options.requestOptionsobjectcontrol some of the behavior of the query
options.requestOptions.forcebooleanfalsealways fetch the latest record
options.requestOptions.capturebooleanfalsecapture the initial state of the record, implies force = true
options.templateobject{}the default template for this query

createStore(options) ⇒ Store

Kind: global function
Returns: Store - a vdata store instance

ParamTypeDefaultDescription
optionsObject
options.modelsObject
options.basePathString''default prefix for http requests
options.adapterfunctiona custom fetch
options.deserializefunctionrequest post-processing

createStore~Store

Kind: inner class of createStore

store.createRecord(collection, data) ⇒ Object

tag a javascript object with metadata that allows it to be tracked by the vdata store. __tmp_id and the idAttribute configured for the given collection are both used to identify the object. editing either of these will cause vdata to see the resulting object as something new that needs to be tracked separately from the original object.

Kind: instance method of Store

ParamTypeDefault
collectionString
dataObject{}

store.get(collectionName, pkOrId) ⇒ Object

get a particular object from the store using the primary key provided by your api server, or the temporary local id that vdata uses internally to track records.

Kind: instance method of Store

ParamType
collectionNameString
pkOrIdString

store.getList(collectionName, keys) ⇒ Array.<object>

get all of the records in collectionName. if you include a keys parameter, this method returns all of the records that match the ids listed.

Kind: instance method of Store

ParamType
collectionNameString
keysArray.<string>

store.remove(collectionName, pkOrId, options) ⇒ Object

remove a record from the store, identified by public key or temporary id.

Kind: instance method of Store
Emits: Store#event:remove

ParamType
collectionNameString
pkOrIdString
optionsObject
options.quietBoolean

store.removeList(collectionName, keys) ⇒ Array.<object>

remove all of the records in collectionName or all of the records that match the ids passed into keys.

Kind: instance method of Store
Emits: Store#event:remove-list

ParamType
collectionNameString
keysArray.<string>

store.clear()

remove all records from all collections

Kind: instance method of Store
Emits: Store#event:remove-list

store.rebase(collection, data) ⇒ Object

vdata automatically tracks all of the versions that are created for every record that it tracks. this version tracking is how Store#rebase is able to implement a simple Observed-Remove Set (ORSet) that enables vdata to deterministically merge all of the changes to a particular record.

given data with a particular __sym_id and the current version of the same record at data[idAttribute], return a merged record containing all changes, applied to the base record at __sym_id in the following order, diff'd against base:

  1. current
  2. data

at CityGro we use the ORSet implementation in vdata to power the real-time features of our customer portal application. in most cases, the core diffing algorithm is able to generate merged outputs with intuitive results. however, it is important to note the rules that we use to resolve certain edge cases.

  1. Last-write (from the perspective of the writer) wins. in our experience, this produces the least surprising results for our users.
  2. Array mutations are all-or-nothing. we currently don't have an acceptable solution to merging arrays with arbitrary mutations. following rule #1, we opt to replace any previous values with the latest version of the array. if you have thoughts on this, please open a ticket on GitLab.

Kind: instance method of Store

ParamType
collectionString
dataObject

store.add(collection, data, options) ⇒ Object

add a record to the store. you do not need to pass your data to Store#createRecord before adding it.

Kind: instance method of Store
Emits: Store#event:add
See: {Store.rebase}

ParamTypeDefaultDescription
collectionString
dataObject
optionsObject
options.quietBooleanfalsesilence store events for this invocation

store.addList(collectionName, data) ⇒ Array.<Object>

add all of the records in data to colectionName in a single operation.

Kind: instance method of Store
Emits: Store#event:add-list

ParamType
collectionNameString
dataArray.<Object>

store.hasChanges(collectionName, data) ⇒ Boolean

check if data differs from the current version of the corresponding record in the store.

Kind: instance method of Store

ParamType
collectionNameString
dataObject

store.destroy(collectionName, data, options) ⇒ Promise.<Object>

send a DELETE request to the endpoint configured for collectionName and remove the corresponding record from the store.

Kind: instance method of Store
Emits: Store#event:remove

ParamType
collectionNameString
dataObject
optionsObject

store.save(collection, data, options) ⇒ Promise.<Object>

persist data using the endpoint configured for collectonName. if data is only identified by a local temporary id send a POST request to /:basePath/:collectionName. if data has a primary key send a PUT request to /:basePath/:collectionName/:primaryKey

when updating an existing record, this methods calls Store#rebase. this gives vdata some important super-powers that you can use to build real-time applications. check the method's docs for details.

Kind: instance method of Store
Emits: Store#event:add

ParamType
collectionString
dataObject
optionsObject

store.find(collection, query, options) ⇒ Promise.<Object>

fetch a particular record from /:basePath/:collectionName/:primaryKey. if force === false immediately return the cached record if present.

Kind: instance method of Store

ParamTypeDefault
collectionString
queryObject
optionsObject
options.forceBooleanfalse

store.findAll(collection, query, options) ⇒ Promise.<Array.<Object>>

fetch all of the records from the api that match the parameters specified in query. these are sent along with the request as query parameters. if force === false immediately return a cached response if one exists.

Kind: instance method of Store

ParamType
collectionString
queryObject
optionsObject

store.on(event, handler)

bind an event listener to the store

Kind: instance method of Store

ParamType
eventString
handlerfunction

store.off(event, handler)

unbind an event listener to the store

Kind: instance method of Store

ParamType
eventString
handlerfunction

store.emit(event, payload)

manually emit a message using the store's event bus

Kind: instance method of Store

ParamType
eventString
payload*

store.getBasePath(collectionName) ⇒ String

get the base path for collectionName

Kind: instance method of Store

ParamType
collectionNameString

store.isValidId(id) ⇒ Boolean

check if the given value is a valid id

Kind: instance method of Store

ParamType
id*

nullify(object) ⇒ Object

replace all values in an object with null. used to generate the ORSet for diffing operations.

Kind: global function

ParamType
objectObject

difference(base, object) ⇒ object

Kind: global function

ParamType
baseobject
objectobject

flattenMixinTree(mixins)

Kind: global function

ParamType
mixinsArray.<Object>

toQueryString(o, prefix)

Kind: global function

ParamType
oobject
prefixstring
9.4.0

7 years ago

9.3.2

7 years ago

9.3.1

7 years ago

9.3.0

7 years ago

9.2.4

7 years ago

9.2.3

7 years ago

9.2.2

7 years ago

9.2.1

7 years ago

9.2.0

7 years ago

9.1.9

7 years ago

9.1.8

7 years ago

9.1.7

7 years ago

9.1.6

7 years ago

9.1.5

7 years ago

9.1.4

7 years ago

9.1.3

7 years ago

9.1.2

7 years ago

9.1.1

7 years ago

9.1.0

7 years ago

9.0.0

7 years ago

8.10.0

7 years ago

8.9.3

7 years ago

8.9.2

7 years ago

8.9.1

7 years ago

8.9.0

7 years ago

8.8.2

7 years ago

8.8.1

7 years ago

8.8.0

7 years ago

8.7.0

7 years ago

8.6.2

7 years ago

8.6.1

7 years ago

8.6.0

7 years ago

8.5.1

7 years ago

8.5.0

7 years ago

8.4.2

7 years ago

8.4.1

7 years ago

8.4.0

7 years ago

8.3.1

7 years ago

8.3.0

7 years ago

8.2.1

7 years ago

8.2.0

7 years ago

8.1.2

7 years ago

8.1.1

7 years ago

8.1.0

7 years ago

8.0.1

7 years ago

8.0.0

7 years ago

7.0.3

7 years ago

7.0.2

7 years ago

7.0.1

7 years ago

7.0.0

7 years ago

6.1.2-0

8 years ago

6.1.1-0

8 years ago

6.1.0-0

8 years ago

6.0.3

8 years ago

6.0.2

8 years ago

6.0.1

8 years ago

6.0.0

8 years ago

5.3.4

8 years ago

5.3.3

8 years ago

5.3.2

8 years ago

5.3.1

8 years ago

5.3.0

8 years ago

5.2.0

8 years ago

5.1.10

8 years ago

5.1.9

8 years ago

5.1.8

8 years ago

5.1.7

8 years ago

5.1.5

8 years ago

5.1.4

8 years ago

5.1.3

8 years ago

5.1.2

8 years ago

5.1.1

8 years ago

5.1.0

8 years ago

5.0.0

8 years ago

4.3.0

8 years ago

4.2.1

8 years ago

4.2.0

8 years ago

4.1.1

8 years ago

4.1.0

8 years ago

4.0.6

8 years ago

4.0.5

8 years ago

4.0.4

8 years ago

4.0.3

8 years ago

4.0.2

8 years ago

4.0.1

8 years ago

4.0.0

8 years ago

3.3.0

8 years ago

3.2.3

8 years ago

3.2.2

8 years ago

3.2.1

8 years ago

3.2.0

8 years ago

3.1.4

8 years ago

3.1.3

8 years ago

3.1.1

8 years ago

3.1.0

8 years ago

3.0.16

8 years ago

3.0.15

8 years ago

3.0.14

8 years ago

3.0.13

8 years ago

3.0.12

8 years ago

3.0.11

8 years ago

3.0.10

8 years ago

3.0.9

8 years ago

3.0.8

8 years ago

3.0.7

8 years ago

3.0.6

8 years ago

3.0.5

8 years ago

3.0.4

8 years ago

3.0.3

8 years ago

3.0.2

8 years ago

3.0.1

8 years ago

3.0.0

8 years ago

2.2.0

8 years ago

2.1.2

8 years ago

2.1.1

8 years ago

2.1.0

8 years ago

2.0.2

8 years ago

2.0.1

8 years ago

1.0.1

8 years ago