@citygro/vdata -- reactive query model

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

| Param | Type | | --- | --- | | value | object | | diff | object |

handleKeyChange

Kind: global constant

| Param | Type | | --- | --- | | value | object | | key | string | | diff | object |

handleArrayChange

Kind: global constant

| Param | Type | | --- | --- | | value | object | | i | number | | diff | object |

handleArrayKeyChange

Kind: global constant

| Param | Type | | --- | --- | | value | object | | i | number | | key | string | | diff | object |

pushToArray

Kind: global constant

| Param | Type | | --- | --- | | value | array | | diff | object |

pushToArrayKey

Kind: global constant

| Param | Type | | --- | --- | | value | object | | key | string | | diff | object |

removeFromArray

Kind: global constant

| Param | Type | | --- | --- | | value | array | | i | number |

removeFromArrayKey

Kind: global constant

| Param | Type | | --- | --- | | value | object | | i | number | | key | string |

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

| Param | Type | Description | | --- | --- | --- | | valueProp | string | bind dataflow to this prop |

add(vm)

register handlers that will run on datastore events

Kind: global function

| Param | Type | | --- | --- | | vm | Vue.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

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | object | | | | options.collectionName | string | | | | options.localPropertyName | string | | the vm data where the result of the query will be stored | | [options.idPropertyName] | string | "id" | the name of the prop you will use to specify the id of the requested record | | [options.requestOptions] | object | | control some of the behavior of the query | | [options.requestOptions.force] | boolean | false | always fetch the latest record | | [options.requestOptions.capture] | boolean | false | capture the initial state of the record, implies force = true | | [options.template] | object | {} | the default template for this query |

createStore(options) ⇒ Store

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | | | options.models | Object | | | | [options.basePath] | String | '' | default prefix for http requests | | [options.adapter] | function | | a custom fetch | | [options.deserialize] | function | | request post-processing |

• createStore(options) ⇒ Store
  • ~Store
    • .createRecord(collection, [data]) ⇒ Object
    • .get(collectionName, pkOrId) ⇒ Object
    • .getList(collectionName, [keys]) ⇒ Array.<object>
    • .remove(collectionName, pkOrId, options) ⇒ Object
    • .removeList(collectionName, keys) ⇒ Array.<object>
    • .clear()
    • .rebase(collection, data) ⇒ Object
    • .add(collection, data, options) ⇒ Object
    • .addList(collectionName, data) ⇒ Array.<Object>
    • .hasChanges(collectionName, data) ⇒ Boolean
    • .destroy(collectionName, data, options) ⇒ Promise.<Object>
    • .save(collection, data, options) ⇒ Promise.<Object>
    • .find(collection, [query], [options]) ⇒ Promise.<Object>
    • .findAll(collection, [query], [options]) ⇒ Promise.<Array.<Object>>
    • .on(event, handler)
    • .off(event, handler)
    • .emit(event, payload)
    • .getBasePath(collectionName) ⇒ String
    • .isValidId(id) ⇒ Boolean

createStore~Store

Kind: inner class of createStore

• ~Store
  • .createRecord(collection, [data]) ⇒ Object
  • .get(collectionName, pkOrId) ⇒ Object
  • .getList(collectionName, [keys]) ⇒ Array.<object>
  • .remove(collectionName, pkOrId, options) ⇒ Object
  • .removeList(collectionName, keys) ⇒ Array.<object>
  • .clear()
  • .rebase(collection, data) ⇒ Object
  • .add(collection, data, options) ⇒ Object
  • .addList(collectionName, data) ⇒ Array.<Object>
  • .hasChanges(collectionName, data) ⇒ Boolean
  • .destroy(collectionName, data, options) ⇒ Promise.<Object>
  • .save(collection, data, options) ⇒ Promise.<Object>
  • .find(collection, [query], [options]) ⇒ Promise.<Object>
  • .findAll(collection, [query], [options]) ⇒ Promise.<Array.<Object>>
  • .on(event, handler)
  • .off(event, handler)
  • .emit(event, payload)
  • .getBasePath(collectionName) ⇒ String
  • .isValidId(id) ⇒ Boolean

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

| Param | Type | Default | | --- | --- | --- | | collection | String | | | [data] | Object | {} |

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

| Param | Type | | --- | --- | | collectionName | String | | pkOrId | String |

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

| Param | Type | | --- | --- | | collectionName | String | | [keys] | Array.<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

| Param | Type | | --- | --- | | collectionName | String | | pkOrId | String | | options | Object | | options.quiet | Boolean |

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

| Param | Type | | --- | --- | | collectionName | String | | keys | Array.<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

| Param | Type | | --- | --- | | collection | String | | data | Object |

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}

| Param | Type | Default | Description | | --- | --- | --- | --- | | collection | String | | | | data | Object | | | | options | Object | | | | [options.quiet] | Boolean | false | silence 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

| Param | Type | | --- | --- | | collectionName | String | | data | Array.<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

| Param | Type | | --- | --- | | collectionName | String | | data | Object |

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

| Param | Type | | --- | --- | | collectionName | String | | data | Object | | options | Object |

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

| Param | Type | | --- | --- | | collection | String | | data | Object | | options | Object |

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

| Param | Type | Default | | --- | --- | --- | | collection | String | | | [query] | Object | | | [options] | Object | | | [options.force] | Boolean | false |

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

| Param | Type | | --- | --- | | collection | String | | [query] | Object | | [options] | Object |

store.on(event, handler)

bind an event listener to the store

Kind: instance method of Store

| Param | Type | | --- | --- | | event | String | | handler | function |

store.off(event, handler)

unbind an event listener to the store

Kind: instance method of Store

| Param | Type | | --- | --- | | event | String | | handler | function |

store.emit(event, payload)

manually emit a message using the store's event bus

Kind: instance method of Store

| Param | Type | | --- | --- | | event | String | | payload | * |

store.getBasePath(collectionName) ⇒ String

get the base path for collectionName

Kind: instance method of Store

| Param | Type | | --- | --- | | collectionName | String |

store.isValidId(id) ⇒ Boolean

check if the given value is a valid id

Kind: instance method of Store

| Param | Type | | --- | --- | | id | * |

nullify(object) ⇒ Object

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

Kind: global function

| Param | Type | | --- | --- | | object | Object |

difference(base, object) ⇒ object

Kind: global function

| Param | Type | | --- | --- | | base | object | | object | object |

flattenMixinTree(mixins)

Kind: global function

| Param | Type | | --- | --- | | mixins | Array.<Object> |

toQueryString(o, prefix)

Kind: global function

| Param | Type | | --- | --- | | o | object | | prefix | string |