DoneJS StealJS jQuery++ FuncUnit DocumentJS
6.6.1
5.33.3 4.3.0 3.14.1 2.3.35
  • About
  • Guides
  • API Docs
  • Community
  • Contributing
  • Bitovi
    • Bitovi.com
    • Blog
    • Design
    • Development
    • Training
    • Open Source
    • About
    • Contact Us
  • About
  • Guides
  • API Docs
    • Observables
      • can-bind
      • can-compute
      • can-debug
      • can-deep-observable
      • can-define
      • can-define/list/list
      • can-define/map/map
      • can-define-backup
      • can-define-stream
      • can-define-stream-kefir
      • can-event-queue
      • can-kefir
      • can-list
      • can-map
      • can-map-compat
      • can-map-define
      • can-observable-array
      • can-observable-object
      • can-observation
      • can-observation-recorder
      • can-observe
      • can-simple-map
      • can-simple-observable
      • can-stream
      • can-stream-kefir
      • can-value
    • Views
      • can-attribute-observable
      • can-component
      • can-observable-bindings
      • can-stache
      • can-stache-bindings
      • can-stache-converters
      • can-stache-element
      • can-stache-route-helpers
      • can-view-autorender
      • can-view-callbacks
      • can-view-import
      • can-view-live
      • can-view-model
      • can-view-parser
      • can-view-scope
      • can-view-target
      • steal-stache
    • Data Modeling
      • can-connect
        • behaviors
          • ./base/
          • ./cache-requests/
          • ./can/constructor-hydrate/
          • ./can/map/
          • ./can/ref/
          • ./can/session/
          • ./can-local-store
          • ./can-memory-store
          • ./constructor/callbacks-once/
          • ./constructor/
          • ./constructor/store/
          • ./data/callbacks/
          • ./data/callbacks-cache/
          • ./data/combine-requests/
          • ./data/parse/
          • ./data/url/
          • ./data/worker/
          • ./fall-through-cache/
          • ./real-time/
        • modules
          • ./can/tag/
          • ./helpers/map-deep-merge
          • ./helpers/weak-reference-map
        • data types
          • DataInterface
          • Instance
          • InstanceInterface
          • List
          • ListData
        • deprecated
          • ./can/base-map/
          • ./can/merge/
            • instance callbacks
              • createdInstance
              • destroyedInstance
              • updatedInstance
              • updatedList
          • ./can/super-map/
          • ./data/localstorage-cache/
          • ./data/memory-cache/
      • can-connect-ndjson
      • can-connect-tag
      • can-define-realtime-rest-model
      • can-define-rest-model
      • can-fixture
      • can-fixture-socket
      • can-local-store
      • can-memory-store
      • can-ndjson-stream
      • can-query-logic
      • can-realtime-rest-model
      • can-rest-model
      • can-set-legacy
      • can-super-model
    • Routing
      • can-deparam
      • can-param
      • can-route
      • can-route-hash
      • can-route-mock
      • can-route-pushstate
    • JS Utilities
      • can-assign
      • can-define-lazy-value
      • can-diff
      • can-globals
      • can-join-uris
      • can-key
      • can-key-tree
      • can-make-map
      • can-parse-uri
      • can-queues
      • can-string
      • can-string-to-any
    • DOM Utilities
      • can-ajax
      • can-attribute-encoder
      • can-child-nodes
      • can-control
      • can-dom-data
      • can-dom-events
      • can-dom-mutate
      • can-event-dom-enter
      • can-event-dom-radiochange
      • can-fragment
    • Data Validation
      • can-type
      • can-validate
      • can-validate-interface
      • can-validate-legacy
      • can-validate-validatejs
    • Typed Data
      • can-cid
      • can-construct
      • can-construct-super
      • can-data-types
      • can-namespace
      • can-reflect
      • can-reflect-dependencies
      • can-reflect-promise
      • can-types
    • Polyfills
      • can-symbol
      • can-vdom
    • Core
    • Infrastructure
      • can-global
      • can-test-helpers
    • Ecosystem
    • Legacy
  • Community
  • Contributing
  • GitHub
  • Twitter
  • Chat
  • Forum
  • News
Bitovi

can/merge

  • Edit on GitHub

Minimally update nested data structures with the response from the server.

Deprecated 5.0

This behavior is built in to can/map.

canMergeBehavior( baseConnection )

Overwrites can/map's instance callbacks so they use can-diff/merge-deep/merge-deep. can-diff/merge-deep/merge-deep is able to make minimal changes to the nested properties of can-define instances and lists given raw data. E.g:

let existingStudent;
const classroom = ClassRoom.get( { id: 505 } ).then( function( instance ) {
    instance.id; // 505
    instance.students[ 0 ].id; // 15
    instance.students[ 0 ].name; // 'Samantha Jones'
    existingStudent = instance;
} );

// later in the program new information for the classroom is retrieved

ClassRoom.get( { id: 505 } ).then( function( instance ) {
    instance.id; // 505
    instance.students[ 0 ].id; // 15
    instance.students[ 0 ].name; // 'Samantha Jones-Baker'

    // true, if can-merge behavior is used.
    // a new nested instance isn't created, instead it was updated with the changed fields
    existingStudent === instance.students[ 0 ];
} );

To use can/merge, the connection's Map, List and any of their nested types must be properly configured. That configuration is discussed in the "Use" section below.

Parameters

  1. baseConnection {Object}:

    can-connect connection object that is having the can/merge behavior added on to it. Expects the can/map behavior to already be added to this base connection. If the connect helper is used to build the connection, the behaviors will automatically be ordered as required.

Returns

{Object}:

a can-connect connection containing the methods provided by can/merge.

Use

To use the can/merge behavior, you have to:

  1. Add the behavior after can/map, and
  2. Make sure all types, especially List type is properly configured.

Adding the can/merge behavior after can/map is pretty straightforward. When you create a custom connection, create it as follows:

import canMergeBehavior from "can-connect/can/merge/merge";
import canMapBehavior from "can-connect/can/map/map";

const ClassRoom = DefineMap.extend( {

    // ...
} );

ClassRoom.List = DefineList.extend( {
    "#": ClassRoom
} );

ClassRoom.queryLogic = new set.Algebra( { /* ... */ } );

ClassRoom.connection = connect( [ /* ... */ , canMapBehavior, canMergeBehavior /* ... */ ], {
    Map: ClassRoom,
    List: ClassRoom.List
} );

For can-diff/merge-deep/merge-deep to merge correctly, it needs to know how to uniquely identify an instance and be able to convert raw data to instances and lists. map-deep-merge looks for this configuration on the .queryLogic and .connection properties of the [can-define.types.TypeConstructor] setting on can-define types.

This is more easily understood in an example. If the ClassRoom has a students property that is a list of Student instances like:

const ClassRoom = DefineMap.extend( {
    students: Student.List
} );

To be able to uniquely identify Student instances within that list, make sure Student has an queryLogic property that is configured with the identifier property:

Student = DefineMap.extend( { /* ... */ } );

Student.queryLogic = new set.Algebra( set.props.id( "_id" ) );

Also make sure that Student.List points its # definition to Student like the following:

Student.List = DefineList.extend( {
    "#": Student
} );

Note: the typical method used to create a Student is new Student(props). However, if Students have a .connection, can-diff/merge-deep/merge-deep will use Student.connection.hydrateInstance(props). This is useful if Students should be looked up in the connection instanceStore.

For example, Student might have a connection that has an instanceStore, like:

Student.connection = baseMap( {
    Map: Student,
    List: Student.List,
    url: "/services/students",
    name: "students"
} );

CanJS is part of DoneJS. Created and maintained by the core DoneJS team and Bitovi. Currently 6.6.1.

On this page

Get help

  • Chat with us
  • File an issue
  • Ask questions
  • Read latest news